Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* makerTransport —— device-link 透明传输层。
* ---------------------------------------------------------------------------
* 让 makerChatStore 的会话操作 / 读取**按 session 来源**自动切换:
* - 本地 session(本机 DB)→ 原样走 window.electronAPI.maker / messageService / sessionService
* - device-link 远程 session(被控设备)→ 走 deviceLink.invoke(deviceId, channel, args) 隧道
*
* 来源判定唯一依据 remoteProjectsStore 的 sessionId→deviceId 注册表(R1 注入)。
* 上层调用点把 `window.electronAPI.maker` 换成 `makerApiFor(sessionId)`、把
* `messageService.list/sessionService.get` 换成这里的 `listMessagesFor/getSessionFor`,
* 其余逻辑零改动 —— 远程会话因此复用同一套 store / reducer / UI。
*
* 注意:被控端 handler 抛的 throwIpcError `[CODE] message` 经隧道原样透传为 reject,
* 上层既有的 extractIpcError / decodeRemoteErrorMessage 继续解码,IPC 错误协议免改。
*/
import {
getSessionDeviceId,
remoteProjectsStore,
} from '@/features/device-link/remoteProjectsStore';
import { isDataOwnerPushCurrent } from '@/contexts/dataOwnerGeneration';
import { isDeviceLinkRemotePushCurrent } from '@/lib/remoteDataOwnerPushFence';
import {
accountCounterAtRequestStart,
invalidationAtRequestStart,
ownerTokenAtRequestStart,
persistCachedMessages,
sessionCacheInvalidationToken,
} from '@/features/device-link/mirrorCacheClient';
import { getStickySessionDeviceId } from '@/features/device-link/stickySessionOrigin';
import type { Message, Session } from '@/lib/ccAgent.types';
import * as messageService from '@/lib/messageService';
import * as sessionService from '@/lib/sessionService';
import { extractIpcError } from '@/utils/ipcError';
import type { TurnChangeSetUpdatedPayload } from '../../shared/turnChangeSet';
import type { LocalPluginOauthRequest, LocalPluginSecretRequest, LocalPluginConnectionRequest } from '../../shared/pluginOauth';
import {
INPUT_HANDOFF_ACTION_ID,
INPUT_HANDOFF_GHOST_ID,
type InputHandoffPicture,
type InputHandoffPresentation,
type InputHandoffSubmission,
} from '@cindy/device-link';
type FullMaker = typeof window.electronAPI.maker;
export type RemoteCredentialSwitchOutcome =
| { kind: 'applied'; sessionId: string }
| { kind: 'failed'; sessionId: string; reason: 'apply-failed' | 'rollback-failed' };
/** A deferred model choice settles on its owning device after the invoke has returned. */
export function subscribeRemoteCredentialSwitchOutcome(
sessionId: string,
deviceId: string | undefined,
callback: (outcome: RemoteCredentialSwitchOutcome) => void,
): () => void {
if (!sessionId) return () => {};
return window.electronAPI.deviceLink.onRemotePush((push, ownerStamp) => {
const sourceDeviceId = deviceId ?? getStickySessionDeviceId(sessionId);
if (!sourceDeviceId || push.deviceId !== sourceDeviceId || !isDeviceLinkRemotePushCurrent(push, ownerStamp)) return;
const payload = push.payload;
if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return;
const value = payload as Record<string, unknown>;
if (value.sessionId !== sessionId) return;
if (push.channel === 'maker:session-credential-switch-applied') {
callback({ kind: 'applied', sessionId });
} else if (push.channel === 'maker:session-credential-switch-failed' &&
(value.reason === 'apply-failed' || value.reason === 'rollback-failed')) {
callback({ kind: 'failed', sessionId, reason: value.reason });
}
});
}
/** The dedicated local Main API owns the browser and encrypted callback; Renderer sees status only. */
export function assistRemotePluginOauth(
sessionId: string,
request: Omit<LocalPluginOauthRequest, 'deviceId'>,
): Promise<{ accepted: boolean }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return Promise.reject(new Error('Remote authorization unavailable'));
return window.electronAPI.maker.assistPluginOauth({ deviceId, ...request });
}
/** This local call goes straight to Main's signed bridge, never makerApiFor/device-link invoke. */
export function submitRemotePluginSecret(
sessionId: string,
request: Omit<LocalPluginSecretRequest, 'deviceId'>,
): Promise<{ accepted: boolean }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return Promise.reject(new Error('Remote authorization unavailable'));
return window.electronAPI.maker.submitRemotePluginSecret({ deviceId, ...request });
}
export function submitRemotePluginConnection(sessionId: string, request: Omit<LocalPluginConnectionRequest, 'deviceId'>): Promise<{ accepted: boolean }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return Promise.reject(new Error('Remote authorization unavailable'));
return window.electronAPI.maker.submitRemotePluginConnection({ deviceId, ...request });
}
/**
* 代输入 values. Local tasks use the trusted local channel; tasks on another
* computer go through Main's signed relay. Never makerApiFor/device-link invoke.
*/
export function submitInputHandoff(
sessionId: string,
request: { submission: InputHandoffSubmission; presentation: InputHandoffPresentation },
): Promise<{ accepted: boolean }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId)
return window.electronAPI.maker.submitInputHandoff(request.presentation.requestId, request.submission);
return window.electronAPI.maker.submitRemoteInputHandoff({
deviceId,
ghostId: INPUT_HANDOFF_GHOST_ID,
requestId: request.presentation.requestId,
actionId: INPUT_HANDOFF_ACTION_ID,
expectedRevision: request.submission.expectedRevision,
submission: request.submission,
presentation: request.presentation,
});
}
/** One opened 代输入 screenshot step: its picture, and one answer (or close). */
export interface InputHandoffPictureSession {
picture: InputHandoffPicture;
answer(submission: InputHandoffSubmission): Promise<{ accepted: boolean }>;
close(): void;
}
/**
* The current screenshot step. On this computer Main hands it over directly;
* for a task on another computer it arrives inside the sealed v3 offer, and
* the answer goes back on the same exchange.
*/
export async function openInputHandoffPicture(
sessionId: string,
presentation: InputHandoffPresentation,
): Promise<InputHandoffPictureSession> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) {
const picture = await window.electronAPI.maker.getInputHandoffPicture(presentation.requestId, presentation.revision);
if (!picture) throw new Error('INPUT_HANDOFF_UNAVAILABLE');
return {
picture,
answer: (submission) => window.electronAPI.maker.submitInputHandoff(presentation.requestId, submission),
close: () => undefined,
};
}
const opened = await window.electronAPI.maker.openRemoteInputHandoffPicture({
deviceId,
ghostId: INPUT_HANDOFF_GHOST_ID,
requestId: presentation.requestId,
actionId: INPUT_HANDOFF_ACTION_ID,
expectedRevision: presentation.revision,
presentation,
});
let open = true;
return {
picture: opened.picture,
answer: (submission) => {
open = false;
return window.electronAPI.maker.answerRemoteInputHandoffPicture(opened.token, submission);
},
close: () => {
if (!open) return;
open = false;
void window.electronAPI.maker.answerRemoteInputHandoffPicture(opened.token, null).catch(() => undefined);
},
};
}
/**
* makerChatStore / ChatInput 经传输层调用的会话操作子集。本地直接复用
* window.electronAPI.maker;远程转 deviceLink.invoke。所有 channel 均在
* REMOTE_INVOKE_ALLOWLIST 白名单内(被控端执行前还会再校验一层)。
*/
export interface RoutableMaker {
predictNextPrompt: FullMaker['predictNextPrompt'];
listBotDelegations: FullMaker['listBotDelegations'];
cancelBotDelegation: FullMaker['cancelBotDelegation'];
getBotDirectMessageThread: FullMaker['getBotDirectMessageThread'];
send: FullMaker['send'];
setModel: FullMaker['setModel'];
// session-agent-switch:跨引擎切换是**会话级**操作,数据真相(pending 意图注册表 +
// 引擎交接)都在会话所在端。远程会话必须隧道到被控端,否则打到控制端本机 maker 上
// 会因本机无此 session 直接失败。只读入口供重连 / 重开视图后恢复 main 权威意图。
switchSessionAgent: FullMaker['switchSessionAgent'];
getSessionAgentSwitchIntent: FullMaker['getSessionAgentSwitchIntent'];
setEffort: FullMaker['setEffort'];
setPermissionMode: FullMaker['setPermissionMode'];
setFastMode: FullMaker['setFastMode'];
setThinkingEnabled: FullMaker['setThinkingEnabled'];
setPlanMode: FullMaker['setPlanMode'];
getSessionTree: FullMaker['getSessionTree'];
navigateSessionTree: FullMaker['navigateSessionTree'];
resolveInteraction: FullMaker['resolveInteraction'];
getPendingInteractions: FullMaker['getPendingInteractions'];
deleteMessage: FullMaker['deleteMessage'];
// —— 完整对等:会话级功能(fork / rewind / context-usage / extra-dirs / close / orca)——
// 本地分支返回完整 maker 天然带这些;远程分支在 remoteMakerApi 里逐一隧道映射。
fork: FullMaker['fork'];
createSideChat: FullMaker['createSideChat'];
listSideChats: FullMaker['listSideChats'];
forkStripEncrypted: FullMaker['forkStripEncrypted'];
rewindPreview: FullMaker['rewindPreview'];
rewindCommit: FullMaker['rewindCommit'];
applyTurnChangeSet: FullMaker['applyTurnChangeSet'];
getContextUsage: FullMaker['getContextUsage'];
setExtraDirs: FullMaker['setExtraDirs'];
setWritableDirs: FullMaker['setWritableDirs'];
closeSession: FullMaker['closeSession'];
// 手动压缩(pi 原生 compact,capability-aware 的 maker:compact-session):
// 上下文环 / 会话菜单对 device-link 远程 pi 会话也要隧道到被控端执行
// (压缩的是被控端的会话上下文,控制端本机无该 live 会话,固定调本机必 null 静默失败)。
compactSession: FullMaker['compactSession'];
enableOrca: FullMaker['enableOrca'];
dispatchOrcaUiAssignment: FullMaker['dispatchOrcaUiAssignment'];
disableOrca: FullMaker['disableOrca'];
input: Pick<
FullMaker['input'],
| 'enqueue'
| 'compact'
| 'steer'
| 'stop'
| 'getProjection'
| 'setExpanded'
| 'resume'
| 'setInteractionLock'
| 'setEditLock'
| 'move'
| 'remove'
| 'updateText'
| 'updateContent'
| 'clearError'
| 'cancelUsageLimitWait'
| 'retryImageDelivery'
| 'retryLastError'
| 'clearSession'
| 'persistTurnErrorDeferred'
>;
}
function invokeRemote(deviceId: string, channel: string, args: unknown[]): Promise<unknown> {
return window.electronAPI.deviceLink.invoke(deviceId, channel, args);
}
type SetModelArgs = Parameters<FullMaker['setModel']>;
/**
* maker:set-model 的 wire 参数不能直接原样转发:Device Link 通过 JSON 传数组,
* undefined 会变成 null。保留中间参数的 null 占位,但裁掉尾部多余的 undefined,
* 使被控端能区分 providerId / revision / selection 的位置而不收到假的尾参。
*/
function buildRemoteSetModelArgs(args: SetModelArgs): unknown[] {
const [sessionId, model, providerId, expectedAgentSwitchRevision, selection] = args;
if (
providerId === undefined &&
(expectedAgentSwitchRevision !== undefined || selection !== undefined)
) {
throw new Error(
'[INVALID_PARAMS] providerId is required when expectedAgentSwitchRevision or selection is provided',
);
}
const wireArgs: unknown[] = [sessionId, model];
if (
providerId !== undefined ||
expectedAgentSwitchRevision !== undefined ||
selection !== undefined
) {
wireArgs.push(providerId === undefined ? null : providerId);
}
if (expectedAgentSwitchRevision !== undefined || selection !== undefined) {
wireArgs.push(expectedAgentSwitchRevision === undefined ? null : expectedAgentSwitchRevision);
}
if (selection !== undefined) wireArgs.push(selection);
return wireArgs;
}
/** 远程被控设备的 maker 操作适配器:每个方法把入参隧道到对应 channel。 */
function remoteMakerApi(deviceId: string): RoutableMaker {
// 除 setModel 外,入参顺序与 window.electronAPI.maker.* / maker:* handler 完全一致。
const t =
(channel: string) =>
(...args: unknown[]): Promise<unknown> =>
invokeRemote(deviceId, channel, args);
return {
predictNextPrompt: t('maker:predict-prompt') as FullMaker['predictNextPrompt'],
listBotDelegations: t('maker:bot-delegations:list') as FullMaker['listBotDelegations'],
cancelBotDelegation: t('maker:bot-delegation:cancel') as FullMaker['cancelBotDelegation'],
getBotDirectMessageThread: t('maker:bot-direct-message-thread:get') as FullMaker['getBotDirectMessageThread'],
applyTurnChangeSet: t('maker:turn-change-set:apply') as FullMaker['applyTurnChangeSet'],
send: t('maker:send') as FullMaker['send'],
setModel: (async (...args: SetModelArgs) =>
invokeRemote(
deviceId,
'maker:set-model',
buildRemoteSetModelArgs(args),
)) as FullMaker['setModel'],
switchSessionAgent: t('maker:switch-session-agent') as FullMaker['switchSessionAgent'],
getSessionAgentSwitchIntent: t(
'maker:get-session-agent-switch-intent',
) as FullMaker['getSessionAgentSwitchIntent'],
setEffort: t('maker:set-effort') as FullMaker['setEffort'],
setPermissionMode: t('maker:set-permission-mode') as FullMaker['setPermissionMode'],
setFastMode: t('maker:set-fast-mode') as FullMaker['setFastMode'],
setThinkingEnabled: t('maker:set-thinking-enabled') as FullMaker['setThinkingEnabled'],
setPlanMode: t('maker:set-plan-mode') as FullMaker['setPlanMode'],
getSessionTree: t('maker:get-session-tree') as FullMaker['getSessionTree'],
navigateSessionTree: t('maker:navigate-session-tree') as FullMaker['navigateSessionTree'],
resolveInteraction: t('maker:resolve-interaction') as FullMaker['resolveInteraction'],
getPendingInteractions: t(
'maker:get-pending-interactions',
) as FullMaker['getPendingInteractions'],
deleteMessage: t('maker:message:delete') as FullMaker['deleteMessage'],
fork: t('maker:fork') as FullMaker['fork'],
createSideChat: t('maker:side-chat:v1') as FullMaker['createSideChat'],
listSideChats: t('maker:side-chat:list:v1') as FullMaker['listSideChats'],
forkStripEncrypted: t('maker:fork-strip-encrypted') as FullMaker['forkStripEncrypted'],
rewindPreview: t('maker:rewind:preview') as FullMaker['rewindPreview'],
rewindCommit: t('maker:rewind:commit') as FullMaker['rewindCommit'],
getContextUsage: t('maker:get-context-usage') as FullMaker['getContextUsage'],
setExtraDirs: t('maker:set-extra-dirs') as FullMaker['setExtraDirs'],
setWritableDirs: t('maker:set-writable-dirs') as FullMaker['setWritableDirs'],
closeSession: t('maker:close-session') as FullMaker['closeSession'],
compactSession: ((sessionId, instructions) =>
invokeRemote(
deviceId,
'maker:compact-session',
instructions === undefined ? [sessionId] : [sessionId, instructions],
)) as FullMaker['compactSession'],
enableOrca: t('maker:session:enable-orca') as FullMaker['enableOrca'],
dispatchOrcaUiAssignment: t(
'maker:worker:dispatch-ui-assignment',
) as FullMaker['dispatchOrcaUiAssignment'],
disableOrca: t('maker:session:disable-orca') as FullMaker['disableOrca'],
input: {
enqueue: t('maker:input:enqueue') as FullMaker['input']['enqueue'],
compact: t('maker:input:compact') as FullMaker['input']['compact'],
steer: t('maker:input:steer') as FullMaker['input']['steer'],
stop: t('maker:input:stop') as FullMaker['input']['stop'],
getProjection: t('maker:input:get-projection') as FullMaker['input']['getProjection'],
setExpanded: t('maker:input:set-expanded') as FullMaker['input']['setExpanded'],
resume: t('maker:input:resume') as FullMaker['input']['resume'],
setInteractionLock: t(
'maker:input:set-interaction-lock',
) as FullMaker['input']['setInteractionLock'],
setEditLock: t('maker:input:set-edit-lock') as FullMaker['input']['setEditLock'],
move: t('maker:input:move') as FullMaker['input']['move'],
remove: t('maker:input:remove') as FullMaker['input']['remove'],
updateText: t('maker:input:update-text') as FullMaker['input']['updateText'],
updateContent: t('maker:input:update-content') as FullMaker['input']['updateContent'],
clearError: t('maker:input:clear-error') as FullMaker['input']['clearError'],
cancelUsageLimitWait: t('maker:input:cancel-usage-limit-wait') as FullMaker['input']['cancelUsageLimitWait'],
retryImageDelivery: t('maker:images:retry') as FullMaker['input']['retryImageDelivery'],
retryLastError: t('maker:input:retry-last-error') as FullMaker['input']['retryLastError'],
clearSession: t('maker:input:clear-session') as FullMaker['input']['clearSession'],
// device-link:auth error 重试失败/放弃时在被控端落库,经隧道路由到被控端 main。
persistTurnErrorDeferred: t(
'maker:persist-turn-error-deferred',
) as FullMaker['input']['persistTurnErrorDeferred'],
},
};
}
/** 已知稳定 deviceId 时直接返回远程 maker 适配器,不重新读取易失 session origin。 */
export function makerApiForDevice(deviceId: string): RoutableMaker {
return remoteMakerApi(deviceId);
}
/** Mutation 前按明确 deviceId 重新读取被控端能力,避免复用可能过期的 renderer cache。 */
export function agentCapabilitiesForDevice(
deviceId: string,
agentKind: 'claude-code' | 'codex' | 'pi',
): Promise<{
supportsOrcaWorkerPermissionMode?: boolean;
supportsDeferredOrcaUiAssignment?: boolean;
supportsOrcaWorkerUpdate?: boolean;
}> {
return invokeRemote(deviceId, 'maker:get-capabilities', [agentKind]) as Promise<{
supportsOrcaWorkerPermissionMode?: boolean;
supportsDeferredOrcaUiAssignment?: boolean;
supportsOrcaWorkerUpdate?: boolean;
}>;
}
/**
* 按 sessionId 来源返回 maker 操作入口:
* - 本地 → 真 window.electronAPI.maker(零开销,行为不变)
* - 远程 → 隧道适配器
*/
export function makerApiFor(sessionId: string): RoutableMaker {
const deviceId = getSessionDeviceId(sessionId);
return deviceId ? makerApiForDevice(deviceId) : window.electronAPI.maker;
}
/**
* 输入框开始打字时请任务所在电脑提前启动 Agent。尽力而为:旧被控端没有该 channel、
* 断线或拒绝都只意味着下一次发送照常冷启动,调用方不需要处理结果。
*/
export function prewarmSessionFor(sessionId: string, createOpts: unknown): Promise<unknown> {
const deviceId = getSessionDeviceId(sessionId);
if (deviceId) return invokeRemote(deviceId, 'maker:session:prewarm', [sessionId, createOpts]);
return window.electronAPI.maker.prewarmSession?.(sessionId, createOpts) ?? Promise.resolve(undefined);
}
/**
* 粘滞归属版 maker 入口:曾解析到 deviceId 的会话,在 relay 瞬时重连清空注册表的窗口内
* 仍走隧道,不会退回本机。
*
* 用于「误判本机会产生副作用」的 **mutation**(与 isRemoteSessionSticky 同一判据,只是那条
* 服务于 gating、这条服务于调用)。协同开关就是典型:enableOrca / disableOrca 在瞬断窗口内
* 被误判成本机,会在**控制端本机**建出或销毁一个 team —— 本机恰好存在同 id 会话时还会操作
* 错对象,而用户看到的入口(按粘滞 remoteDeviceId 渲染)分明指向被控端(issue #1170 codex P2)。
*
* 普通高频操作(send / setModel / …)仍用 makerApiFor:它们本就跟随会话来源的实时判定,
* 且误判的代价是一次失败重试,不是在错误的机器上留下持久状态。
*/
export function makerApiForSticky(sessionId: string): RoutableMaker {
const deviceId = getStickySessionDeviceId(sessionId);
return deviceId ? makerApiForDevice(deviceId) : window.electronAPI.maker;
}
/** Subscribe to summaries from the owning device; exact patches are fetched on demand. */
export function subscribeTurnChangeSetUpdated(
sessionId: string,
cb: (payload: TurnChangeSetUpdatedPayload) => void,
): () => void {
const bind = (deviceId: string | undefined): (() => void) => {
if (!deviceId) {
return window.electronAPI.maker.onTurnChangeSetUpdated((raw, ownerStamp) => {
if (!isDataOwnerPushCurrent(ownerStamp)) return;
const payload = raw as Partial<TurnChangeSetUpdatedPayload> | null;
if (payload?.sessionId !== sessionId || !payload.summary) return;
cb(payload as TurnChangeSetUpdatedPayload);
});
}
return window.electronAPI.deviceLink.onRemotePush((push, localOwnerStamp) => {
if (push.deviceId !== deviceId || push.channel !== 'maker:turn-change-set:updated') return;
if (!isDeviceLinkRemotePushCurrent(push, localOwnerStamp)) return;
const payload = push.payload as Partial<TurnChangeSetUpdatedPayload> | null;
if (payload?.sessionId !== sessionId || payload.summary?.sessionId !== sessionId) return;
cb(payload as TurnChangeSetUpdatedPayload);
});
};
let currentDeviceId = getStickySessionDeviceId(sessionId);
let offInner = bind(currentDeviceId);
const offStore = remoteProjectsStore.subscribe(() => {
const nextDeviceId = getStickySessionDeviceId(sessionId);
if (nextDeviceId === currentDeviceId) return;
currentDeviceId = nextDeviceId;
offInner();
offInner = bind(nextDeviceId);
});
return () => {
offStore();
offInner();
};
}
/** 是否远程(device-link)会话。 */
export function isRemoteSession(sessionId: string): boolean {
return getSessionDeviceId(sessionId) !== undefined;
}
/**
* 粘滞版远程判定:曾解析到 deviceId 的会话在 relay 瞬时重连清空注册表的窗口内
* 仍视为远程。用于「误判本机会产生副作用」的 gating(如 Stop 按钮 —— 瞬断窗口
* 误判本机会放出按钮,点击走本地 stopAgentTask 假成功,任务在被控端继续跑)。
*/
export function isRemoteSessionSticky(sessionId: string): boolean {
return getStickySessionDeviceId(sessionId) !== undefined;
}
/**
* 重命名输入框 Magic 按钮:按会话最新对话重生成标题。
* 远程会话隧道到被控端执行——对话素材与 provider 凭证的数据真相都在被控端;
* 老被控端无此 channel 时 invoke 以 CHANNEL_NOT_ALLOWED 拒绝,调用方按生成失败提示。
*/
export function regenerateSessionTitleFor(sessionId: string): Promise<{ title: string | null }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.maker.regenerateSessionTitle(sessionId);
return invokeRemote(deviceId, 'maker:regenerate-title', [{ sessionId }]) as Promise<{
title: string | null;
}>;
}
/** 读会话元数据:远程走隧道 local-db:sessions:get(本地 DB 没有该 row,直接调会 404)。 */
export function getSessionFor(sessionId: string): Promise<Session> {
// Session metadata is part of the same remote send attempt as the later
// enqueue. Keep using the last known device while the mirror is being
// rebuilt; reading the controller's local DB in that window returns either
// an unrelated row or a misleading 404 and can make a UI trigger fall back
// to the wrong maker instance.
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return sessionService.get(sessionId);
return invokeRemote(deviceId, 'local-db:sessions:get', [sessionId]) as Promise<Session>;
}
/**
* 查被控端某会话的权威 turn 运行态(远程走隧道 maker:session-in-turn)。
* 控制端 stall 看门狗用:卡死 Generating 但久未收 push 时核实被控端是否真的还在跑——
* 答 false 才安全收尾,绝不误杀真正在跑的慢 turn。
* 本机会话不走看门狗 → 直接 resolve(false)(调用方已 gate,这里仅防御)。
*/
export function isSessionTurnRunningFor(sessionId: string): Promise<boolean> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return Promise.resolve(false);
return invokeRemote(deviceId, 'maker:session-in-turn', [sessionId]) as Promise<boolean>;
}
/**
* 「应用退出中断」横幅的运行态真值:时间戳来自哪台设备的 session 行,就问哪台设备。
* 远程会话的 turn 只在被控端跑,控制端本机 main 永远答「不在 turn 中」,拿它当真值会把
* 被控端正在跑的任务误判成中断。deviceId 由调用方显式传入(视图的粘滞归属),不在这里
* 重新解析易失的 session origin —— 重连窗口内退回本机同样会得到错误的 false。
*/
export async function getSessionTurnActiveOn(
sessionId: string,
deviceId: string | null | undefined,
): Promise<boolean> {
if (!deviceId) {
const result = await window.electronAPI.maker.getSessionTurnActive(sessionId);
return result?.inTurn === true;
}
return (await invokeRemote(deviceId, 'maker:session-in-turn', [sessionId])) === true;
}
/**
* 读历史消息:远程走隧道 local-db:messages:list,返回形状与本地一致(camelCase Message[])。
*
* 远程会话取回**最新一页**(没有 before / beforeTs 游标)时顺手写进冷缓存
* (`mirrorCacheClient`),供下次冷启动 / 被控端离线时乐观渲染。这是缓存的**唯一写点**:
* 首拉、reconcileRemoteMessages、reconnect 重拉、turn 结束对账都经过这里,所以缓存
* 自然跟着最近一次对账保持新鲜。翻页(before/beforeTs)与本机会话都不写 ——
* 老窗口不是"最近一页",写进去会让下次冷开 hydrate 出一段历史中间的孤岛。
*/
export function listMessagesFor(
sessionId: string,
opts?: { limit?: number; before?: string; beforeTs?: number },
): Promise<Message[]> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return messageService.list(sessionId, opts);
const promise = invokeRemote(deviceId, 'local-db:messages:list', [sessionId, opts]) as Promise<
Message[]
>;
if (!opts?.before && opts?.beforeTs == null) {
// 发起时的作废令牌:/clear、rewind、删消息都会自增它(见 clearCachedMessages)。
const invalidationAtStart = sessionCacheInvalidationToken(sessionId);
// 同时记下 main 侧的会话级作废计数(跨窗口 / 跨进程可见);落盘时交给 main 比对。
// 还没有已知值时**在这里**(与远端请求同时)补读一次 —— main 拒绝没带令牌的非空写入,
// 而补读若拖到落盘前做,拿到的是清理之后的值,屏障就失效了(见 invalidationAtRequestStart)。
const mainInvalidationAtStart = invalidationAtRequestStart(deviceId, sessionId);
// opaque owner token 只信任受保护读(readCachedMessages,经 main 原子复核)带回的值:有已知值同步
// 返回;有在途受保护读则等它完成(账号切换后首次打开会话时 hydrate 读在并行);都没有才
// undefined → 由 store fail-closed 丢弃。绝不单独 getMessages 补读,避免补读 IPC 在账号
// 切换后才被 main 处理、把新账号 token 当成本次请求的 owner 锚点(review: codex P1 + Greptile)。
const ownerTokenAtStart = ownerTokenAtRequestStart(sessionId);
// 账号代际计数同源:同一账号登出再登录时 token 不变,靠它区分登出前后的内容。
const accountCounterAtStart = accountCounterAtRequestStart(sessionId);
void promise
.then((rows) => {
if (!Array.isArray(rows)) return;
// 请求在途期间权威侧作废过这个会话的历史 → 手里这批是作废前的行,丢弃这次写,
// 否则它会排在那次空写之后落地,把已被清掉的正文重新写回盘上(review: pr-code-review)。
if (sessionCacheInvalidationToken(sessionId) !== invalidationAtStart) return;
// 请求在途期间这台设备可能已被撤销 / 关闭被控 / 本机停用控制,那条路径已经
// clearCachedDevice 清过盘了。迟到的响应若照写,会用清理**之后**的 main 代际
// 把被撤销对端的明文重新落盘,main 侧的作废闸挡不住它(review: codex P1)。
// 落盘前重核归属:mapping 已经不在(或已换设备)就直接丢弃这次写入。
if (getSessionDeviceId(sessionId) !== deviceId) return;
// 把"我取到内容时 main 侧的会话级作废计数"一起交上去:main 会再比对一次,于是
// **另一个窗口 / 另一个进程**的作废也能挡住这次写(renderer 令牌只在本进程内可见)。
// opaque owner token 同理:它是「这份内容在哪个账号名下取的」的身份标记,账号切换后 main 靠
// 它丢弃上一个账号的在途响应(review: #1783)。accountCounter 再补「同账号登出再登录」。
// 两者取不到时(补读在途 / 失败)传 undefined,由 main 侧 fail-closed 判断。
persistCachedMessages(
deviceId,
sessionId,
rows,
mainInvalidationAtStart,
ownerTokenAtStart,
accountCounterAtStart,
);
})
// 拉取失败由调用方处理;这里只是不写缓存(旧缓存保留,离线时正好还能用)。
.catch(() => undefined);
}
return promise;
}
const BACKGROUND_TASK_OUTPUT_TAIL_UNSUPPORTED_TTL_MS = 10 * 60 * 1000;
const backgroundTaskOutputTailUnsupportedUntil = new Map<string, number>();
/**
* 运行中后台命令的输出文件末尾一段(只读,best-effort):任务登记与 `.output` 文件都在会话归属端,
* 远程会话隧道到被控端读。老被控端无此 channel → CHANNEL_NOT_ALLOWED → 带 TTL
* 短路(与 workflow 进度同款);其余错误一律按 read_failed 返回,调用方不显示最近输出。
*/
export function readBackgroundTaskOutputTailFor(
sessionId: string,
taskId: string,
): Promise<import('../../shared/backgroundTaskOutput').BackgroundTaskOutputTailResult> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) {
return window.electronAPI.maker
.readBackgroundTaskOutputTail(sessionId, taskId)
.catch(() => ({ ok: false, reason: 'read_failed' }) as const);
}
const blockedUntil = backgroundTaskOutputTailUnsupportedUntil.get(deviceId);
if (blockedUntil !== undefined && blockedUntil > Date.now()) {
return Promise.resolve({ ok: false, reason: 'unavailable' });
}
return (
invokeRemote(deviceId, 'maker:background-task:output-tail', [sessionId, taskId]) as Promise<
import('../../shared/backgroundTaskOutput').BackgroundTaskOutputTailResult
>
).catch((err) => {
if (extractIpcError(err)?.code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED') {
backgroundTaskOutputTailUnsupportedUntil.set(
deviceId,
Date.now() + BACKGROUND_TASK_OUTPUT_TAIL_UNSUPPORTED_TTL_MS,
);
return { ok: false, reason: 'unavailable' } as const;
}
return { ok: false, reason: 'read_failed' } as const;
});
}
// 已确认不支持 maker:get-workflow-progress 的被控设备(收到过 CHANNEL_NOT_ALLOWED):
// 短路一段时间不再空耗隧道往返。带 TTL 而非进程级永久 —— deviceId 跨升级稳定,
// 被控端升级到支持版本后负缓存到期自动重探,无需重启控制端。
const WORKFLOW_PROGRESS_UNSUPPORTED_TTL_MS = 10 * 60 * 1000;
const workflowProgressUnsupportedUntil = new Map<string, number>();
/**
* workflow 逐 agent 进度树(只读,best-effort):记录文件真相在会话归属端 HOME,
* 远程会话必须隧道到被控端读(控制端本机读必落空)。老被控端无此 channel →
* CHANNEL_NOT_ALLOWED → 记入带 TTL 的短路表;其余错误一律返回 null,调用方回退
* workflow 级卡片。
*/
export function getWorkflowProgressFor(
sessionId: string,
taskId: string,
): Promise<import('../../shared/workflow-progress').WorkflowProgress | null> {
// 粘滞归属(与 listSessionBackgroundTasksFor 同款):relay 瞬时重连清空注册表的
// 窗口内误判本机会在本地读必空,且详情视图不会因归属恢复而重试。
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.maker.getWorkflowProgress(sessionId, taskId);
const blockedUntil = workflowProgressUnsupportedUntil.get(deviceId);
if (blockedUntil !== undefined && blockedUntil > Date.now()) return Promise.resolve(null);
return (
invokeRemote(deviceId, 'maker:get-workflow-progress', [sessionId, taskId]) as Promise<
import('../../shared/workflow-progress').WorkflowProgress | null
>
).catch((err) => {
if (extractIpcError(err)?.code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED') {
workflowProgressUnsupportedUntil.set(
deviceId,
Date.now() + WORKFLOW_PROGRESS_UNSUPPORTED_TTL_MS,
);
}
return null;
});
}
/**
* 会话仍在运行的后台任务快照(只读,best-effort):后台任务面板挂载时补回
* 「订阅前已启动 / 重载清空 taskUpdates 后」的存量任务。远程会话任务真身在
* 被控端,必须隧道读(控制端 main 无该会话 handle,本机读必空);老被控端无此
* channel 或隧道失败一律降级空表,面板退化为事件流 + 消息扫描两源。
* 归属用粘滞解析(与 estimatedSessionValueFor 同款):这是一次性水合,relay
* 瞬时重连清空注册表的窗口内若误判为本机,会 seed 一张空表且面板不重试。
*/
export function listSessionBackgroundTasksFor(
sessionId: string,
): ReturnType<typeof window.electronAPI.maker.listSessionBackgroundTasks> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.maker.listSessionBackgroundTasks(sessionId);
return (
invokeRemote(deviceId, 'maker:session-background-tasks:list', [sessionId]) as ReturnType<
typeof window.electronAPI.maker.listSessionBackgroundTasks
>
).catch(() => ({ tasks: [] }));
}
/**
* 会话后台活动快照(只读,best-effort):「turn 已结束但子进程仍在调模型」的信号
* 由被控端 loopback proxy 观察,远程会话必须隧道读(控制端本机查恒为 false)。
* 隧道失败一律按无活动降级,与 listSessionBackgroundTasksFor 同口径。
*/
export async function sessionBackgroundActivityFor(sessionId: string): Promise<{ active: boolean }> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.maker.getSessionBackgroundActivity(sessionId);
return (
invokeRemote(deviceId, 'maker:session-background-activity', [sessionId]) as Promise<{
active: boolean;
}>
).catch(() => ({ active: false }));
}
/**
* 停止类操作的执行端:远程 → 被控设备 id(粘滞解析,relay 瞬断窗口内不退回本机);
* 本机 → null,但仅当本机库确有该会话。两者都不是即归属未解析(冷启动时远程注册表
* 尚未就绪),拒绝执行 —— 本机停止对不存在的会话会幂等「成功」,任务却在被控端继续跑。
*/
async function resolveStopOwner(sessionId: string): Promise<string | null> {
const deviceId = getStickySessionDeviceId(sessionId);
if (deviceId) return deviceId;
try {
await sessionService.get(sessionId);
} catch {
throw new Error('[DEVICE_LINK_NOT_CONNECTED] Background task ownership is unresolved');
}
// 本机查询在途期间远程注册表可能完成水合(恢复 / 复制的本机库可含同 id 会话):
// 查询落地后再核验一次,远程归属优先,停止不落到同 id 的本机会话。
return getStickySessionDeviceId(sessionId) ?? null;
}
/**
* 精确停止单个后台任务,在会话归属端执行(见 resolveStopOwner)。错误原样透传:
* 老被控端回 DEVICE_LINK_CHANNEL_NOT_ALLOWED,调用方据此提示升级。
*/
export async function stopAgentTaskFor(sessionId: string, taskId: string): Promise<{ ok: true }> {
const deviceId = await resolveStopOwner(sessionId);
if (!deviceId) return window.electronAPI.maker.stopAgentTask(sessionId, taskId);
return invokeRemote(deviceId, 'maker:agent-task:stop', [sessionId, taskId]) as Promise<{
ok: true;
}>;
}
/** 会话级「全部停止」(关闭归属端常驻 agent 进程);路由与错误语义同 stopAgentTaskFor。 */
export async function stopSessionBackgroundTasksFor(sessionId: string): Promise<{ ok: true }> {
const deviceId = await resolveStopOwner(sessionId);
if (!deviceId) return window.electronAPI.maker.stopSessionBackgroundTasks(sessionId);
return invokeRemote(deviceId, 'maker:session-background-tasks:stop', [sessionId]) as Promise<{
ok: true;
}>;
}
/**
* 订阅形态会话「本会话价值」历史汇总:远程走隧道(否则查控制端空库恒为 0,底部 $ chip
* 的历史初值永远缺失)。归属用粘滞解析(relay 瞬时重连清空注册表的窗口内不误判为本机,
* 与 goal/learn 链路同款);老被控端无此 channel → CHANNEL_NOT_ALLOWED,调用方 catch
* 后退化为只显示已加载消息 + 实时推送的部分值。
*/
export function estimatedSessionValueFor(sessionId: string): Promise<{
totalValueMoney?: import('../../shared/regionalMoney').RegionalMoney | null;
totalValueUsd?: number;
entries: Array<{
clientId: string;
money?: import('../../shared/regionalMoney').RegionalMoney;
costUsd?: number;
turnUsageDetails?: unknown;
}>;
}> {
const deviceId = getStickySessionDeviceId(sessionId);
if (!deviceId) return messageService.estimatedSessionValue(sessionId);
return invokeRemote(deviceId, 'local-db:messages:estimatedSessionValue', [
sessionId,
]) as ReturnType<typeof estimatedSessionValueFor>;
}
/**
* 插件启停状态(只读):**按目标设备**读项目级 / 用户级 collab 等开关。
*
* device-link 会话与草稿的 workingDir 是**被控端**机器上的路径,拿它在控制端本机查
* `.cindy/plugins.json` 读到的是控制端自己的用户级开关 —— 与被控端 main 的权威授权
* (assertCollabProjectEnabled)可能相反,于是入口看得见却开不起来(issue #1170)。
* 所以这里按 deviceId 分流:本机 → 真 IPC;远程 → 隧道到被控端读它自己的真相。
*
* 路径归一化由调用方在控制端完成:normalizeWorkingDirForProjectSettings 是纯路径形态
* 推导(不依赖 process.platform / 本机 userData),跨 macOS ↔ Windows 控制同样成立。
*
* 老被控端未收录该 channel 时隧道回 DEVICE_LINK_CHANNEL_NOT_ALLOWED,调用方据此
* fail-closed 置灰入口并说明「设备版本过旧」,不会放行到 enableOrca 才撞错。
*/
export function pluginEnableStateFor(
deviceId: string | null | undefined,
pluginId: string,
workingDir?: string,
workspaceKind?: string | null,
): ReturnType<typeof window.electronAPI.maker.plugins.getState> {
if (!deviceId) {
return workspaceKind === undefined
? window.electronAPI.maker.plugins.getState(pluginId, workingDir)
: window.electronAPI.maker.plugins.getState(pluginId, workingDir, workspaceKind);
}
const args =
workspaceKind === undefined ? [pluginId, workingDir] : [pluginId, workingDir, workspaceKind];
return invokeRemote(deviceId, 'maker:plugins:get-state', args) as ReturnType<
typeof window.electronAPI.maker.plugins.getState
>;
}
/** 会话内搜索跳转定位:远程走隧道 local-db:messages:around(否则查控制端空库,跳转必失败)。 */
export function aroundMessagesFor(
sessionId: string,
messageId: string,
opts?: { radius?: number },
): Promise<Message[]> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return messageService.around(sessionId, messageId, opts);
return invokeRemote(deviceId, 'local-db:messages:around', [
sessionId,
messageId,
opts,
]) as Promise<Message[]>;
}
/**
* error-tail-banner「关闭/忽略」:按会话来源路由 dismiss-error(main 侧 merge
* dismissed:true)。远程会话必须写到被控端 DB —— 只改控制端内存的话,重连 /
* 历史重拉 / 重启后错误行的 dismissed 仍为空,红条会复活(review P2)。
* 老被控端未收录该 channel 时隧道回 CHANNEL_NOT_ALLOWED,调用方 catch 后
* 退化为本视图内存隐藏。
*/
export function dismissErrorMessageFor(sessionId: string, clientId: string): Promise<unknown> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return messageService.dismissError(sessionId, clientId);
return invokeRemote(deviceId, 'local-db:messages:dismiss-error', [sessionId, clientId]);
}
/** 消息删除:user 只删目标行,assistant 删除所属整轮输出。 */
export interface MessageDeletionResult {
sessionId: string;
clientId: string;
/** 老被控端只回 clientId;新 host 返回本次原子删除的完整范围。 */
clientIds?: string[];
}
export function deleteMessageFor(
sessionId: string,
clientId: string,
): Promise<MessageDeletionResult> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.maker.deleteMessage(sessionId, clientId);
return invokeRemote(deviceId, 'maker:message:delete', [
sessionId,
clientId,
]) as Promise<MessageDeletionResult>;
}
/** interrupted-turn-resume:中断提示「忽略」的显式确认(写一次 last_turn_ended_at),
* 远程会话经隧道落被控端 DB;老被控端 CHANNEL_NOT_ALLOWED 由调用方吞错降级。
* 「继续任务」主路径在执行端 main 的 onDispatchedUserTurn 里 durable ack
* (排队阶段不 ack,便于取消后恢复横幅);session 行缺失走 direct-send 兜底时,
* ack 由执行端 maker:send 事务在 accepted 后完成,本函数只服务显式「忽略」。 */
export function ackInterruptedTurnFor(sessionId: string): Promise<unknown> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return window.electronAPI.localDb.sessions.ackInterrupted(sessionId);
return invokeRemote(deviceId, 'local-db:sessions:ack-interrupted', [sessionId]);
}
/** fork 来源定位:forkedAtMessageId 存的是 clientId,远程同样走被控端 DB。 */
export function aroundMessagesByClientIdFor(
sessionId: string,
clientId: string,
opts?: { radius?: number },
): Promise<Message[]> {
const deviceId = getSessionDeviceId(sessionId);
if (!deviceId) return messageService.aroundClientId(sessionId, clientId, opts);
return invokeRemote(deviceId, 'local-db:messages:around-client-id', [
sessionId,
clientId,
opts,
]) as Promise<Message[]>;
}
/**
* 已知稳定 deviceId 时直接查询 clientId 锚点。远程乐观发送用它核实一个
* ACK 丢失的 steer 是否已经落库;这里不能重新读取易失的 session origin,
* 否则恰好在重连清镜像的窗口会误查控制端本机 DB。
*/
export function aroundMessagesByClientIdForDevice(
deviceId: string,
sessionId: string,
clientId: string,
opts?: { radius?: number },
): Promise<Message[]> {
return invokeRemote(deviceId, 'local-db:messages:around-client-id', [
sessionId,
clientId,
opts,
]) as Promise<Message[]>;
}
// ─── /goal:device-link 远程路由 ────────────────────────────────────────────────
// goal-host 在「会话归属设备」上跑(目标随会话在被控端自主续跑,控制端断链不中断)。
// GoalIndicator / NewGoalDialog / useGoalStatus 经这里按会话来源路由;状态推送
// (maker:goal:status-changed,带 sessionId → session:<id> topic)经 subscribeGoalStatusChanged。
// 归属解析是**惰性 + 粘滞**的(Codex review #548,learnTransport 同款):不在构造时
// 快照(origin 注入前会钉死在本机),解析到过 deviceId 后不因 relay 重连清镜像而降级回本机。
type FullGoalMaker = Pick<
FullMaker,
'setGoal' | 'clearGoal' | 'pauseGoal' | 'resumeGoal' | 'updateGoal' | 'getGoalStatus'
>;
/** goal 操作的可路由子集(订阅另走 subscribeGoalStatusChanged)。 */
export type RoutableGoal = FullGoalMaker;
// goal 归属解析:粘滞状态在模块级缓存(stickySessionOrigin),跨适配器重建 /
// effect 重跑存活 —— relay 重连清镜像触发的重建不会丢掉归属。
/**
* 按会话来源返回 goal 操作入口:本机 → 真 window.electronAPI.maker;远程 → 隧道到
* 归属设备(channel/args 与 preload goal 块逐一对齐;updateGoal 在 preload 里把位置参
* 打包成 { sessionId, patch },这里同样打包)。每次方法调用时重新解析归属。
*/
export function goalApiFor(sessionId: string): RoutableGoal {
const resolve = () => getStickySessionDeviceId(sessionId);
const t =
(channel: string, local: (...args: never[]) => unknown) =>
(...args: unknown[]): Promise<unknown> => {
const deviceId = resolve();
if (!deviceId) return Promise.resolve(local(...(args as never[])));
return invokeRemote(deviceId, channel, args);
};
const localApi = window.electronAPI.maker;
return {
setGoal: t('maker:goal:set', localApi.setGoal) as FullMaker['setGoal'],
clearGoal: t('maker:goal:clear', localApi.clearGoal) as FullMaker['clearGoal'],
pauseGoal: t('maker:goal:pause', localApi.pauseGoal) as FullMaker['pauseGoal'],
resumeGoal: t('maker:goal:resume', localApi.resumeGoal) as FullMaker['resumeGoal'],
updateGoal: ((sid: string, patch: unknown) => {
const deviceId = resolve();
if (!deviceId)
return localApi.updateGoal(sid, patch as Parameters<FullMaker['updateGoal']>[1]);
return invokeRemote(deviceId, 'maker:goal:update', [{ sessionId: sid, patch }]);
}) as FullMaker['updateGoal'],
getGoalStatus: t('maker:goal:get-status', localApi.getGoalStatus) as FullMaker['getGoalStatus'],
};
}
/**
* 订阅某会话的 goal 状态变化(payload = { sessionId, goal }):
* - 本机会话 → 本机 onGoalStatusChanged IPC(按 sessionId 过滤);
* - 远程会话 → device-link 远程推送(被控端 maker:goal:status-changed 经
* session:<id> topic 转发;打开该会话视图即已订阅),按 deviceId + sessionId 过滤。
* 归属在订阅期间可能变化(origin 注入 / 重连恢复)—— 内部监听 remoteProjectsStore,
* 解析结果变化时自动拆旧绑新。返回 unsubscribe。
*/
export function subscribeGoalStatusChanged(
sessionId: string,
cb: (payload: { sessionId: string; goal: GoalStatusPayload | null }) => void,
): () => void {
const resolve = () => getStickySessionDeviceId(sessionId);
const bind = (deviceId: string | undefined): (() => void) => {
if (!deviceId) {
return window.electronAPI.maker.onGoalStatusChanged((payload) => {
if (payload.sessionId !== sessionId) return;
cb(payload);
});
}
return (
window.electronAPI.deviceLink?.onRemotePush?.((push, localOwnerStamp) => {
if (push.deviceId !== deviceId || push.channel !== 'maker:goal:status-changed') return;
if (!isDeviceLinkRemotePushCurrent(push, localOwnerStamp)) return;
const payload = push.payload as { sessionId?: string; goal?: GoalStatusPayload | null };
if (payload?.sessionId !== sessionId) return;
cb(payload as { sessionId: string; goal: GoalStatusPayload | null });
}) ?? (() => {})
);
};
let current = resolve();
let offInner = bind(current);
const offStore = remoteProjectsStore.subscribe(() => {
const next = resolve();
if (next === current) return;
current = next;
offInner();
offInner = bind(next);
});
return () => {
offStore();
offInner();
};
}
// ─── orca 团队读 / 管理:device-link 远程路由 ───────────────────────────────────
// 远程会话开协同:worker session 真身在被控端,控制端纯镜像。团队读模型(get-by-lead /
// list-workers-by-lead / get-by-worker-session)与管理动作(create/switch/idle/archive/end-team)
// 都按 ctx session 的来源路由——本机原样走 localDb.orcaWorkflows,远程隧道到被控端。
type FullOrca = typeof window.electronAPI.localDb.orcaWorkflows;
/**
* orca 读/管理的可路由子集(排除 onOrcaWorkerChanged 订阅,见 subscribeOrcaWorkerChanged)。
* 只列「确有远程调用方 + channel 在 REMOTE_INVOKE_ALLOWLIST 内」的方法。刻意不暴露
* updateWorkerStatus / setCollaborationSetting:它们无远程调用方,且对应 channel 不在
* allowlist(远程调会 CHANNEL_NOT_ALLOWED)。Team / Worker 创建只能走 maker lifecycle
* IPC,以便 Main 在写入前执行实时项目策略授权。
* makerTransportOrcaRouting.test.ts 有 drift 守卫:适配器里每个 channel 串都必须在 allowlist 内。
*/
export interface RoutableOrcaWorkflows {
getByLeadSession: FullOrca['getByLeadSession'];
getByWorkerSession: FullOrca['getByWorkerSession'];
listWorkersByLead: FullOrca['listWorkersByLead'];
createWorker: FullOrca['createWorker'];
switchFocus: FullOrca['switchFocus'];
idleWorker: FullOrca['idleWorker'];
archiveWorker: FullOrca['archiveWorker'];
/** 修改 worker 的展示角色名与 team 内唯一标识。 */
updateWorker: FullOrca['updateWorker'];
endTeam: FullOrca['endTeam'];
getCollaborationSettings: FullOrca['getCollaborationSettings'];
listExecutionDevices: FullOrca['listExecutionDevices'];
}
/**
* 远程被控设备的 orca 适配器:每个方法把入参隧道到对应 channel,channel/args 与 preload 的
* orcaWorkflows 块逐一对齐。多数方法 preload 直接把入参透传给 invoke(故通用 t 转发即可);
* idle/archive 在 preload 里把位置参打包成单对象,这里同样打包后再隧道。
* 仅暴露 allowlist 内、确有远程调用方的方法(见 RoutableOrcaWorkflows 注释)。
*/
function remoteOrcaWorkflows(deviceId: string): RoutableOrcaWorkflows {
const t =
(channel: string) =>
(...args: unknown[]): Promise<unknown> =>
invokeRemote(deviceId, channel, args);
return {
getByLeadSession: t('local-db:orca-workflows:get-by-lead') as FullOrca['getByLeadSession'],
getByWorkerSession: t(
'local-db:orca-workflows:get-by-worker-session',
) as FullOrca['getByWorkerSession'],
listWorkersByLead: t(
'local-db:orca-workflows:list-workers-by-lead',
) as FullOrca['listWorkersByLead'],
createWorker: t('maker:worker:create') as FullOrca['createWorker'],
switchFocus: t('maker:worker:switch-focus') as FullOrca['switchFocus'],
idleWorker: ((leadSessionId: string, workerId: string, expectedStatus?: 'done') => {
if (expectedStatus === 'done') {
return invokeRemote(deviceId, 'maker:worker:acknowledge-done', [
{ leadSessionId, workerId },
]);
}
return invokeRemote(deviceId, 'maker:worker:idle', [
{
leadSessionId,
workerId,
...(expectedStatus ? { expectedStatus } : {}),
},
]);
}) as FullOrca['idleWorker'],
archiveWorker: ((leadSessionId: string, workerId: string) =>
invokeRemote(deviceId, 'maker:worker:archive', [
{ leadSessionId, workerId },
])) as FullOrca['archiveWorker'],
updateWorker: ((input: {
leadSessionId: string;
workerId: string;
role?: string;
label?: string;
}) => invokeRemote(deviceId, 'maker:worker:update', [input])) as FullOrca['updateWorker'],
endTeam: t('maker:team:end') as FullOrca['endTeam'],
getCollaborationSettings: t(
'maker:collaboration-settings:get',
) as FullOrca['getCollaborationSettings'],
listExecutionDevices: t('maker:orca:execution-devices') as FullOrca['listExecutionDevices'],
};
}
/**
* 按 ctx session 来源返回 orca 操作入口:本机 → 真 window.electronAPI.localDb.orcaWorkflows;
* 远程 → 隧道适配器。lead 相关方法传 leadSessionId 作 ctx;getByWorkerSession 传 workerSessionId
* 作 ctx(reseed 后 worker sessionId 已注册到被控端 deviceId)。
*/
export function orcaWorkflowsFor(contextSessionId: string): RoutableOrcaWorkflows {
const deviceId = getSessionDeviceId(contextSessionId);
return deviceId ? remoteOrcaWorkflows(deviceId) : window.electronAPI.localDb.orcaWorkflows;
}
/**
* 已知稳定 deviceId 时直接返回远程 orca 适配器,不重新读取易失的 session origin
* (与 makerApiForDevice 同款)。用于「调用方手里已经握着权威 deviceId」的场景 ——
* 例如刚在该被控端建出会话、要回查它的权威团队终态。
*/
export function orcaWorkflowsForDevice(deviceId: string): RoutableOrcaWorkflows {
return remoteOrcaWorkflows(deviceId);
}
/**
* 订阅某 lead 的 orca worker 变更并在变更时回调:
* - 本机 lead → 本机 `onOrcaWorkerChanged` IPC(按 leadSessionId 过滤)。
* - 远程 lead → device-link 远程推送(被控端 `maker:orca:worker-changed` 经隧道转发;
* 前提是该 lead 会话已订阅 `session:<leadId>` 重 topic,即 orca lead 视图已打开)。
* 返回 unsubscribe。
*/
export function subscribeOrcaWorkerChanged(leadSessionId: string, cb: () => void): () => void {
// 订阅与 Orca 投影查询一样使用粘滞归属。relay 瞬时重连会清空
// remoteProjectsStore;此时不能把仍属于被控端的 Lead 改订到控制端本机事件源。
const deviceId = getStickySessionDeviceId(leadSessionId);
if (!deviceId) {
return (
window.electronAPI.localDb.orcaWorkflows.onOrcaWorkerChanged?.((payload: unknown) => {
if ((payload as { leadSessionId?: string })?.leadSessionId === leadSessionId) cb();
}) ?? (() => {})
);
}
return (
window.electronAPI.deviceLink?.onRemotePush?.((push, localOwnerStamp) => {
if (
push.deviceId === deviceId &&
push.channel === 'maker:orca:worker-changed' &&
(push.payload as { leadSessionId?: string })?.leadSessionId === leadSessionId
) {
if (!isDeviceLinkRemotePushCurrent(push, localOwnerStamp)) return;
cb();
}
}) ?? (() => {})
);
}