Skip to content

armgit / cindy

Public Imported from GitHub
0

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

feat(desktop): 供应商组第二期——分享的人经组所在电脑中转

Lizid6842886b5cb
diff --git a/apps/desktop/src/main/provider-group/__tests__/guestRelay.test.ts b/apps/desktop/src/main/provider-group/__tests__/guestRelay.test.ts
new file mode 100644
index 0000000000..63c2644b28
--- /dev/null
+++ b/apps/desktop/src/main/provider-group/__tests__/guestRelay.test.ts
@@ -0,0 +1,97 @@
+/**
+ * 组所在电脑替受邀者选组内电脑(provider-groups.md §4、§9):只选能按受邀者隔离的电脑;不支持的
+ * 同账号电脑一阵子不再给它受邀者的任务,但不冷却它(本机自己的任务照常分过去)。
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ProviderGroupConfig, ProviderGroupMember } from '../../../shared/providerGroup';
+import { createProviderGroupExternalLoad } from '../externalLoad';
+import { createProviderGroupGuestRelay, PROVIDER_GROUP_GUEST_INCAPABLE_MS } from '../guestRelay';
+import { PROVIDER_GROUP_DEFAULT_COOLDOWN_MS, type ProviderGroupRouter } from '../router';
+
+function member(key: string, kind: ProviderGroupMember['kind'], agentDeviceId: string | null, providerId: string): ProviderGroupMember {
+ return { key, kind, agentDeviceId, providerId, limit: 4, weight: 1, paused: false };
+}
+
+const LOCAL = member('local', 'local', null, 'anthropic');
+const MINI = member('device:mini:anthropic-2', 'device', 'mini', 'anthropic-2');
+const FRIEND = member('share:s1:anthropic', 'share', 'share:s1', 'anthropic');
+const CONFIG: ProviderGroupConfig = { strategy: 'order', autoSwitch: true, members: [LOCAL, MINI, FRIEND] };
+
+function setup(picks: ProviderGroupMember[]) {
+ let now = 1_000;
+ const router = {
+ pick: vi.fn(async ({ exclude }: { exclude?: ReadonlySet<string> }) => {
+ const next = picks.find((m) => !exclude?.has(m.key));
+ return next ? { kind: 'member' as const, member: next, label: next.key, resolved: [] } : { kind: 'unavailable' as const, resolved: [] };
+ }),
+ view: vi.fn(),
+ running: vi.fn(() => 0),
+ markCooling: vi.fn(),
+ coolingUntil: vi.fn(() => null),
+ markTried: vi.fn(() => new Set<string>()),
+ triedThisTurn: vi.fn(() => new Set<string>()),
+ resetTurn: vi.fn(),
+ } as unknown as ProviderGroupRouter & { pick: ReturnType<typeof vi.fn>; markCooling: ReturnType<typeof vi.fn> };
+ const externalLoad = createProviderGroupExternalLoad({ now: () => now });
+ const invoke = vi.fn(async () => ({}));
+ const relay = createProviderGroupGuestRelay({
+ router,
+ readGroup: (id) => (id === 'anthropic' ? CONFIG : null),
+ externalLoad,
+ connect: () => ({ invoke, poller: {} as never }),
+ now: () => now,
+ log: { warn: vi.fn() },
+ });
+ return { relay, router, externalLoad, invoke, advance: (ms: number) => { now += ms; } };
+}
+
+const PLAN = { kind: 'claude-code' as const, model: 'opus', providerId: 'anthropic', exclude: new Set<string>() };
+
+describe('provider group guest relay planner', () => {
+ it('maps the picked computer: this computer runs locally, others are relayed', async () => {
+ expect(await setup([LOCAL]).relay.plan(PLAN)).toEqual({ kind: 'local' });
+ expect(await setup([MINI]).relay.plan(PLAN)).toEqual({
+ kind: 'member', memberKey: MINI.key, agentDeviceId: 'mini', providerId: 'anthropic-2', sameAccount: true,
+ });
+ expect(await setup([FRIEND]).relay.plan(PLAN)).toEqual({
+ kind: 'member', memberKey: FRIEND.key, agentDeviceId: 'share:s1', providerId: 'anthropic', sameAccount: false,
+ });
+ expect(await setup([]).relay.plan(PLAN)).toEqual({ kind: 'unavailable' });
+ expect(await setup([MINI]).relay.plan({ ...PLAN, providerId: 'openai' })).toBeNull();
+ });
+
+ it('skips a same-account computer that cannot isolate shared users for a while, without cooling it', async () => {
+ const env = setup([MINI, FRIEND]);
+ env.relay.noteStartFailure('anthropic', { memberKey: MINI.key, agentDeviceId: 'mini', providerId: MINI.providerId, sameAccount: true },
+ new Error('[REMOTE_AGENT_PEER_TOO_OLD] old'));
+ expect(env.router.markCooling).not.toHaveBeenCalled();
+ expect((await env.relay.plan(PLAN))).toMatchObject({ memberKey: FRIEND.key });
+ env.advance(PROVIDER_GROUP_GUEST_INCAPABLE_MS + 1);
+ expect((await env.relay.plan(PLAN))).toMatchObject({ memberKey: MINI.key });
+ });
+
+ it('cools a computer that failed to start for a reason of its own', async () => {
+ const env = setup([MINI]);
+ env.relay.noteStartFailure('anthropic', { memberKey: MINI.key, agentDeviceId: 'mini', providerId: MINI.providerId, sameAccount: true },
+ new Error('prompt is too long'));
+ expect(env.router.markCooling).not.toHaveBeenCalled();
+ env.relay.noteStartFailure('anthropic', { memberKey: MINI.key, agentDeviceId: 'mini', providerId: MINI.providerId, sameAccount: true },
+ new Error('[REMOTE_AGENT_DEVICE_UNREACHABLE] gone'));
+ expect(env.router.markCooling).toHaveBeenCalledWith('anthropic', MINI.key, expect.any(Number));
+ expect(env.router.markCooling.mock.calls[0][2]).toBeLessThan(1_000 + PROVIDER_GROUP_DEFAULT_COOLDOWN_MS);
+ });
+
+ it('counts relayed tasks while they run and asks computers to forget a shared user', async () => {
+ const env = setup([MINI]);
+ const load = env.relay.trackRun('anthropic', MINI.key);
+ expect(env.externalLoad.running('anthropic', MINI.key)).toBe(1);
+ load.setRunning(false);
+ expect(env.externalLoad.running('anthropic', MINI.key)).toBe(0);
+ load.setRunning(true);
+ load.release();
+ expect(env.externalLoad.running('anthropic', MINI.key)).toBe(0);
+ await env.relay.forget('mini', 'a'.repeat(32));
+ expect(env.invoke).toHaveBeenCalledWith([{ op: 'forget', relay: 'a'.repeat(32) }]);
+ });
+});
diff --git a/apps/desktop/src/main/provider-group/externalLoad.ts b/apps/desktop/src/main/provider-group/externalLoad.ts
index a21028b9b2..725d8e758a 100644
--- a/apps/desktop/src/main/provider-group/externalLoad.ts
+++ b/apps/desktop/src/main/provider-group/externalLoad.ts
@@ -25,6 +25,10 @@ export interface ProviderGroupExternalLoad {
recordPick(controller: string, sessionId: string, providerId: string, memberKey: string): void;
/** 某台电脑的整份报告;返回 false = 比已有的旧,被丢弃。 */
replaceLeases(controller: string, seq: number, entries: readonly ProviderGroupRemoteLease[]): boolean;
+ /**
+ * 本机替受邀者中转到这台组内电脑的任务(本机能看到它是否在运行一轮):任务结束时 release。
+ */
+ trackRelay(providerId: string, memberKey: string): { setRunning(running: boolean): void; release(): void };
}
interface LeaseSet {
@@ -44,6 +48,7 @@ interface Provisional {
export function createProviderGroupExternalLoad(deps: { now(): number }): ProviderGroupExternalLoad {
const leases = new Map<string, LeaseSet>();
const provisional = new Map<string, Provisional>();
+ const relays = new Set<{ providerId: string; memberKey: string; running: boolean }>();
const provisionalKey = (controller: string, sessionId: string) => `${controller}\u0000${sessionId}`;
function liveLeases(controller: string): LeaseSet | null {
@@ -82,9 +87,26 @@ export function createProviderGroupExternalLoad(deps: { now(): number }): Provid
if (reported.has(key)) continue;
if (entry.providerId === providerId && entry.memberKey === memberKey) count++;
}
+ for (const relay of relays) {
+ if (relay.running && relay.providerId === providerId && relay.memberKey === memberKey) count++;
+ }
return count;
},
+ trackRelay(providerId, memberKey) {
+ // 刚交过去、还没报运行状态的先按在运行算(同时来的几个受邀者任务不会全落到同一台)。
+ const entry = { providerId, memberKey, running: true };
+ relays.add(entry);
+ return {
+ setRunning(running) {
+ entry.running = running;
+ },
+ release() {
+ relays.delete(entry);
+ },
+ };
+ },
+
recordPick(controller, sessionId, providerId, memberKey) {
const now = deps.now();
sweepProvisional(now);
diff --git a/apps/desktop/src/main/provider-group/guestRelay.ts b/apps/desktop/src/main/provider-group/guestRelay.ts
new file mode 100644
index 0000000000..a771313e0b
--- /dev/null
+++ b/apps/desktop/src/main/provider-group/guestRelay.ts
@@ -0,0 +1,100 @@
+/**
+ * 供应商组替受邀者选电脑(docs/product-rules/provider-groups.md §4、§9):本机是组所在电脑,受邀者用的是
+ * 本机分享出去的供应商,而这个供应商建了组。受邀者连不到组内其他电脑,由本机选一台并中转
+ * (中转本身在 remote-agent/host/runHost.ts)。
+ *
+ * 只选能接受受邀者的电脑:本机;分享来的电脑(那台本来就把本机当受邀者隔离);同账号电脑要它声明
+ * `guestRelay`(能按受邀者隔离),否则受邀者在那台会拿到主人级权限。不支持的同账号电脑暂时不再给它分
+ * 受邀者的任务,但不冷却它,本机自己的任务照常分过去。
+ */
+import type { AgentKind } from '@cindy/maker-core';
+
+import type { ProviderGroupConfig } from '../../shared/providerGroup.js';
+import type { GroupRelayMember, RemoteAgentGroupRelayDeps } from '../remote-agent/host/runHost.js';
+import type { RemoteAgentInvoke, RemoteAgentPoller } from '../remote-agent/controller/runClient.js';
+import type { ProviderGroupExternalLoad } from './externalLoad.js';
+import {
+ PROVIDER_GROUP_DEFAULT_COOLDOWN_MS,
+ PROVIDER_GROUP_FAILURE_COOLDOWN_MS,
+ type ProviderGroupRouter,
+} from './router.js';
+import { classifyProviderGroupSwitchCause } from './switchCause.js';
+
+/** 同账号电脑不支持接受受邀者任务时,多久内不再试它。 */
+export const PROVIDER_GROUP_GUEST_INCAPABLE_MS = 10 * 60_000;
+
+export interface ProviderGroupGuestRelayDeps {
+ router: ProviderGroupRouter;
+ readGroup(providerId: string): ProviderGroupConfig | null;
+ externalLoad: ProviderGroupExternalLoad;
+ connect(agentDeviceId: string): { invoke: RemoteAgentInvoke; poller: RemoteAgentPoller };
+ now(): number;
+ log: { warn(message: string, meta?: Record<string, unknown>): void };
+}
+
+function errorText(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+export function createProviderGroupGuestRelay(deps: ProviderGroupGuestRelayDeps): RemoteAgentGroupRelayDeps {
+ /** 不支持接受受邀者任务的同账号电脑 → 到何时前不再试。 */
+ const incapable = new Map<string, number>();
+
+ function isIncapable(agentDeviceId: string): boolean {
+ const until = incapable.get(agentDeviceId);
+ if (until === undefined) return false;
+ if (until <= deps.now()) {
+ incapable.delete(agentDeviceId);
+ return false;
+ }
+ return true;
+ }
+
+ return {
+ async plan({ kind, model, providerId, exclude }) {
+ const config = deps.readGroup(providerId);
+ if (!config) return null;
+ const skip = new Set(exclude);
+ for (const member of config.members) {
+ if (member.kind === 'device' && member.agentDeviceId && isIncapable(member.agentDeviceId)) skip.add(member.key);
+ }
+ const pick = await deps.router.pick({ providerId, agentKind: kind as AgentKind, model, exclude: skip });
+ if (pick.kind === 'none') return null;
+ if (pick.kind === 'unavailable') return { kind: 'unavailable' };
+ const { member } = pick;
+ if (member.kind === 'local' || !member.agentDeviceId) return { kind: 'local' };
+ return {
+ kind: 'member',
+ memberKey: member.key,
+ agentDeviceId: member.agentDeviceId,
+ providerId: member.providerId,
+ sameAccount: member.kind === 'device',
+ };
+ },
+
+ connect: (agentDeviceId) => deps.connect(agentDeviceId),
+
+ noteStartFailure(providerId, member: GroupRelayMember, error) {
+ const message = errorText(error);
+ // 那台太旧、还不能按受邀者隔离:不冷却它(本机自己的任务照常分过去),只是一阵子不再给它受邀者的任务。
+ if (/REMOTE_AGENT_PEER_TOO_OLD|REMOTE_AGENT_UNSUPPORTED/.test(message)) {
+ incapable.set(member.agentDeviceId, deps.now() + PROVIDER_GROUP_GUEST_INCAPABLE_MS);
+ return;
+ }
+ const cause = classifyProviderGroupSwitchCause({ message });
+ if (!cause) return;
+ const now = deps.now();
+ deps.router.markCooling(
+ providerId,
+ member.memberKey,
+ now + (cause === 'usage-limit' ? PROVIDER_GROUP_DEFAULT_COOLDOWN_MS : PROVIDER_GROUP_FAILURE_COOLDOWN_MS),
+ );
+ },
+
+ trackRun: (providerId, memberKey) => deps.externalLoad.trackRelay(providerId, memberKey),
+
+ async forget(agentDeviceId, relay) {
+ await deps.connect(agentDeviceId).invoke([{ op: 'forget', relay }]);
+ },
+ };
+}
diff --git a/apps/desktop/src/main/provider-group/runtime.ts b/apps/desktop/src/main/provider-group/runtime.ts
index c85a4b0d0f..70650de365 100644
--- a/apps/desktop/src/main/provider-group/runtime.ts
+++ b/apps/desktop/src/main/provider-group/runtime.ts
@@ -72,6 +72,7 @@ const externalLoadFacade: ProviderGroupExternalLoad = {
recordPick: (controller, sessionId, providerId, memberKey) =>
runtimeForActiveOwner().externalLoad.recordPick(controller, sessionId, providerId, memberKey),
replaceLeases: (controller, seq, entries) => runtimeForActiveOwner().externalLoad.replaceLeases(controller, seq, entries),
+ trackRelay: (providerId, memberKey) => runtimeForActiveOwner().externalLoad.trackRelay(providerId, memberKey),
};
const routerFacade: ProviderGroupRouter = {
diff --git a/apps/desktop/src/main/remote-agent/__tests__/groupRelay.test.ts b/apps/desktop/src/main/remote-agent/__tests__/groupRelay.test.ts
new file mode 100644
index 0000000000..92c3010026
--- /dev/null
+++ b/apps/desktop/src/main/remote-agent/__tests__/groupRelay.test.ts
@@ -0,0 +1,294 @@
+/**
+ * 供应商组替受邀者中转(docs/product-rules/provider-groups.md §4、§9),三端同进程、经 JSON 往返模拟设备互联:
+ * 受邀者 G ⇄ 组所在电脑 O(createRemoteAgentHost + groupRelay) ⇄ 组内电脑 M(createRemoteAgentHost)。
+ * - 受邀者的新任务按组交给 M;M 按受邀者隔离运行(受邀者目录、会话索引按 relay 分开);
+ * - 两个受邀者用同一个任务 id 不会在 M 上撞车;续接只回到当初那台;不能接回别的受邀者的会话;
+ * - 启动阶段那台接不下(不支持按受邀者隔离)就换下一台;
+ * - 删掉受邀者时请 M 清掉它留下的东西,M 只清调用方自己的 relay。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { AgentEvent, AgentSessionHandle } from '@cindy/maker-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { RemoteAgentPoller } from '../controller/poller';
+import { RemoteAgentRunClient } from '../controller/runClient';
+import { relayKeyFor } from '../host/groupRelay';
+import {
+ createRemoteAgentHost,
+ hostSessionIdFor,
+ type GroupRelayMember,
+ type GroupRelayPlan,
+ type HostedStartInput,
+ type RemoteAgentGroupRelayDeps,
+} from '../host/runHost';
+
+const GUEST_A = 'share-guest-a';
+const GUEST_B = 'share-guest-b';
+const OWNER_DEVICE = 'group-owner-mac';
+const SESSION = 'task-1';
+
+let root: string;
+
+interface Started {
+ input: HostedStartInput;
+ sends: unknown[];
+}
+
+function fakeAgentHost(name: string, started: Started[], options: {
+ trust: (controller: string) => 'guest' | 'owner';
+ guestRelayCapable?: boolean;
+ purge?: (hostSessionIds: readonly string[], nativeIds: readonly string[]) => Promise<void>;
+ groupRelay?: RemoteAgentGroupRelayDeps;
+}) {
+ return createRemoteAgentHost({
+ isAgentAvailable: () => true,
+ startHosted: async (input) => {
+ const record: Started = { input, sends: [] };
+ started.push(record);
+ const handle: AgentSessionHandle = {
+ id: `sdk-${name}-${input.hostSessionId}`,
+ agentKind: input.kind,
+ model: input.options.model,
+ async send(message) {
+ record.sends.push(message);
+ },
+ async steer() {},
+ async abort() {},
+ async close() {},
+ events: () => ({
+ [Symbol.asyncIterator]: (): AsyncIterator<AgentEvent> => ({
+ next: () => new Promise<IteratorResult<AgentEvent>>(() => undefined),
+ }),
+ }),
+ getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
+ setInteractionResolver() {},
+ };
+ return handle;
+ },
+ isControllerAuthorized: () => true,
+ controllerTrust: options.trust,
+ providerAccess: {
+ resolve: async (_kind, _model, providerId) => providerId ?? 'shared-provider',
+ isAllowed: () => true,
+ },
+ ...(options.guestRelayCapable === false ? {} : {
+ bindGuestProviderRoute: async () => ({ routeToken: 'route', modelIds: ['claude-opus'], release: () => {} }),
+ }),
+ ...(options.purge ? { purgeHostedTranscripts: options.purge } : {}),
+ ...(options.groupRelay ? { groupRelay: options.groupRelay } : {}),
+ captureOwner: () => 'owner',
+ isOwnerCurrent: () => true,
+ runsRoot: path.join(root, name),
+ });
+}
+
+function openPayload(sessionId: string, extra: Record<string, unknown> = {}) {
+ return {
+ sessionId,
+ virtualWorkspace: true,
+ options: { model: 'claude-opus', ...(extra.options as object | undefined) },
+ workspace: { workingDir: '/Users/guest/proj', platform: 'darwin', shell: 'zsh' },
+ projectFiles: [],
+ ancestorFiles: [],
+ personal: { files: [] },
+ mcpServers: [],
+ ...Object.fromEntries(Object.entries(extra).filter(([key]) => key !== 'options')),
+ };
+}
+
+const jsonRoundTrip = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+async function waitFor(condition: () => boolean, ms = 3_000): Promise<void> {
+ const deadline = Date.now() + ms;
+ while (!condition()) {
+ if (Date.now() > deadline) throw new Error('timed out waiting');
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ }
+}
+
+const MEMBER_MINI: GroupRelayMember = { memberKey: 'device:mini:anthropic-2', agentDeviceId: 'mini', providerId: 'anthropic-2', sameAccount: true };
+const MEMBER_STUDIO: GroupRelayMember = { memberKey: 'device:studio:anthropic', agentDeviceId: 'studio', providerId: 'anthropic', sameAccount: true };
+
+function setup(options: { plans?: GroupRelayPlan[]; miniCapable?: boolean } = {}) {
+ const memberStarted: Record<string, Started[]> = { mini: [], studio: [] };
+ const members = {
+ mini: fakeAgentHost('mini', memberStarted.mini, {
+ trust: () => 'owner',
+ guestRelayCapable: options.miniCapable ?? true,
+ purge: async () => undefined,
+ }),
+ studio: fakeAgentHost('studio', memberStarted.studio, { trust: () => 'owner', purge: async () => undefined }),
+ };
+ const memberInvoke = (agentDeviceId: string) => async (args: unknown[]) =>
+ jsonRoundTrip(await members[agentDeviceId as keyof typeof members].handle(OWNER_DEVICE, jsonRoundTrip(args[0])));
+ const pollers = new Map<string, RemoteAgentPoller>();
+ const plans = [...(options.plans ?? [{ kind: 'member', ...MEMBER_MINI }])];
+ const relay = {
+ plan: vi.fn(async () => plans.shift() ?? null),
+ connect: vi.fn((agentDeviceId: string) => {
+ let poller = pollers.get(agentDeviceId);
+ if (!poller) {
+ poller = new RemoteAgentPoller(memberInvoke(agentDeviceId));
+ pollers.set(agentDeviceId, poller);
+ }
+ return { invoke: poller.invoke, poller };
+ }),
+ noteStartFailure: vi.fn(),
+ trackRun: vi.fn(() => ({ setRunning: vi.fn(), release: vi.fn() })),
+ forget: vi.fn(async (agentDeviceId: string, relayKey: string) => {
+ await memberInvoke(agentDeviceId)([{ op: 'forget', relay: relayKey }]);
+ }),
+ } satisfies RemoteAgentGroupRelayDeps;
+ const ownerStarted: Started[] = [];
+ const owner = fakeAgentHost('owner', ownerStarted, {
+ trust: (controller) => (controller.startsWith('share-') ? 'guest' : 'owner'),
+ purge: async () => undefined,
+ groupRelay: relay,
+ });
+ return { owner, members, memberStarted, ownerStarted, relay };
+}
+
+beforeEach(() => {
+ root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cindy-group-relay-')));
+});
+
+afterEach(() => {
+ fs.rmSync(root, { recursive: true, force: true });
+});
+
+let runSeq = 0;
+function runId(): string {
+ runSeq += 1;
+ return `11111111-1111-4111-8111-${String(runSeq).padStart(12, '0')}`;
+}
+
+async function openAsGuest(env: ReturnType<typeof setup>, guest: string, payload: Record<string, unknown>) {
+ const poller = new RemoteAgentPoller(async (args) => jsonRoundTrip(await env.owner.handle(guest, jsonRoundTrip(args[0]))));
+ let counter = 0;
+ const client = new RemoteAgentRunClient(runId(), poller, {
+ onEvent: () => undefined,
+ onState: () => undefined,
+ onRequest: async () => ({ type: 'callback', value: undefined }),
+ onWs: () => undefined,
+ onClosed: () => undefined,
+ }, () => `22222222-2222-4222-8222-${String(++counter + runSeq * 100).padStart(12, '0')}`);
+ const started = await client.open('claude-code', payload);
+ return { client, started };
+}
+
+describe('provider group relay for shared users', () => {
+ it('hands a shared user’s new task to the chosen computer, which runs it isolated as a shared user', async () => {
+ const env = setup();
+ const { client, started } = await openAsGuest(env, GUEST_A, openPayload(SESSION));
+ expect(env.ownerStarted).toHaveLength(0);
+ expect(env.memberStarted.mini).toHaveLength(1);
+ const input = env.memberStarted.mini[0].input;
+ expect(input.guest).toBe(true);
+ expect(input.guestProvider?.providerId).toBe('anthropic-2');
+ expect(input.options.providerId).toBe('anthropic-2');
+ // 组内电脑上的任务 id 按受邀者派生,不是受邀者原来的 id。
+ expect(input.hostSessionId).not.toBe(hostSessionIdFor(OWNER_DEVICE, SESSION));
+ expect(input.guestHome).toContain(path.join('mini', 'guest-homes'));
+ expect(started.id).toBe(`sdk-mini-${input.hostSessionId}`);
+ await client.call('send', [{ content: 'hello', attachments: [] }, {}]);
+ expect(env.memberStarted.mini[0].sends).toHaveLength(1);
+ expect(env.relay.trackRun).toHaveBeenCalledWith('shared-provider', MEMBER_MINI.memberKey);
+ await client.close('close', 'navigation');
+ });
+
+ it('keeps two shared users apart on the computer even with the same task id', async () => {
+ const env = setup({ plans: [{ kind: 'member', ...MEMBER_MINI }, { kind: 'member', ...MEMBER_MINI }] });
+ const a = await openAsGuest(env, GUEST_A, openPayload(SESSION));
+ const b = await openAsGuest(env, GUEST_B, openPayload(SESSION));
+ const [first, second] = env.memberStarted.mini.map((record) => record.input);
+ expect(first.hostSessionId).not.toBe(second.hostSessionId);
+ expect(first.guestHome).not.toBe(second.guestHome);
+ await a.client.close('close', 'navigation');
+ await b.client.close('close', 'navigation');
+ });
+
+ it('resumes only on the computer that ran the conversation, and never another shared user’s', async () => {
+ const env = setup();
+ const first = await openAsGuest(env, GUEST_A, openPayload(SESSION));
+ const nativeId = first.started.id as string;
+ await first.client.close('close', 'navigation');
+ await waitFor(() => env.members.mini.runCount() === 0);
+
+ const resumed = await openAsGuest(env, GUEST_A, openPayload(SESSION, { options: { resumeSessionId: nativeId } }));
+ expect(env.relay.plan).toHaveBeenCalledTimes(1);
+ expect(env.memberStarted.mini).toHaveLength(2);
+ expect(env.memberStarted.mini[1].input.options.resumeSessionId).toBe(nativeId);
+ await resumed.client.close('close', 'navigation');
+
+ await expect(openAsGuest(env, GUEST_B, openPayload(SESSION, { options: { resumeSessionId: nativeId } })))
+ .rejects.toThrow(/cannot be resumed/);
+ });
+
+ it('moves on to the next computer when the first cannot isolate shared users', async () => {
+ const env = setup({ miniCapable: false, plans: [{ kind: 'member', ...MEMBER_MINI }, { kind: 'member', ...MEMBER_STUDIO }] });
+ const { client } = await openAsGuest(env, GUEST_A, openPayload(SESSION));
+ expect(env.memberStarted.mini).toHaveLength(0);
+ expect(env.memberStarted.studio).toHaveLength(1);
+ expect(env.relay.noteStartFailure).toHaveBeenCalledWith('shared-provider', MEMBER_MINI, expect.any(Error));
+ expect(env.relay.plan).toHaveBeenLastCalledWith(expect.objectContaining({ exclude: new Set([MEMBER_MINI.memberKey]) }));
+ await client.close('close', 'navigation');
+ });
+
+ it('runs locally when the group picks this computer, and refuses when no computer can run it', async () => {
+ const local = setup({ plans: [{ kind: 'local' }] });
+ const { client } = await openAsGuest(local, GUEST_A, openPayload(SESSION));
+ expect(local.ownerStarted).toHaveLength(1);
+ expect(local.ownerStarted[0].input.guest).toBe(true);
+ await client.close('close', 'navigation');
+
+ const none = setup({ plans: [{ kind: 'unavailable' }] });
+ await expect(openAsGuest(none, GUEST_A, openPayload(SESSION))).rejects.toThrow(/REMOTE_AGENT_UNAVAILABLE/);
+ });
+
+ it('asks the computer to forget a removed shared user, and the computer clears only that user', async () => {
+ const env = setup({ plans: [{ kind: 'member', ...MEMBER_MINI }, { kind: 'member', ...MEMBER_MINI }] });
+ const a = await openAsGuest(env, GUEST_A, openPayload(SESSION));
+ const b = await openAsGuest(env, GUEST_B, openPayload(SESSION));
+ const homeA = env.memberStarted.mini[0].input.guestHome!;
+ const homeB = env.memberStarted.mini[1].input.guestHome!;
+ expect(fs.existsSync(homeA) && fs.existsSync(homeB)).toBe(true);
+ await env.owner.purgeControllers((controller) => controller === GUEST_A);
+ await waitFor(() => !fs.existsSync(homeA));
+ expect(env.relay.forget).toHaveBeenCalledWith('mini', relayKeyFor(GUEST_A));
+ expect(fs.existsSync(homeB)).toBe(true);
+ // 另一个控制端拿着同一个 relay 键也清不掉别人的。
+ await env.members.mini.handle('someone-else', { op: 'forget', relay: relayKeyFor(GUEST_B) });
+ expect(fs.existsSync(homeB)).toBe(true);
+ await b.client.close('close', 'navigation');
+ void a;
+ });
+
+ it('runs a relayed task from a same-account computer as a shared user, never with owner trust', async () => {
+ const started: Started[] = [];
+ const member = fakeAgentHost('member', started, { trust: () => 'owner' });
+ const poller = new RemoteAgentPoller(async (args) => jsonRoundTrip(await member.handle(OWNER_DEVICE, jsonRoundTrip(args[0]))));
+ const client = new RemoteAgentRunClient(runId(), poller, {
+ onEvent: () => undefined,
+ onState: () => undefined,
+ onRequest: async () => ({ type: 'callback', value: undefined }),
+ onWs: () => undefined,
+ onClosed: () => undefined,
+ }, () => '33333333-3333-4333-8333-333333333333');
+ await client.open('claude-code', openPayload('relayed', { relay: relayKeyFor(GUEST_A), groupAssigned: true }));
+ expect(started[0].input.guest).toBe(true);
+ // 被中转的任务不能凭 id 接上这台主人自己的会话。
+ await expect(new RemoteAgentRunClient(runId(), poller, {
+ onEvent: () => undefined,
+ onState: () => undefined,
+ onRequest: async () => ({ type: 'callback', value: undefined }),
+ onWs: () => undefined,
+ onClosed: () => undefined,
+ }, () => '44444444-4444-4444-8444-444444444444')
+ .open('claude-code', openPayload('relayed-2', { relay: relayKeyFor(GUEST_A), options: { resumeSessionId: 'owner-native' } })))
+ .rejects.toThrow(/cannot be resumed/);
+ await client.close('close', 'navigation');
+ });
+});
diff --git a/apps/desktop/src/main/remote-agent/__tests__/plumbing.test.ts b/apps/desktop/src/main/remote-agent/__tests__/plumbing.test.ts
index 01e869a65d..ea3233ced6 100644
--- a/apps/desktop/src/main/remote-agent/__tests__/plumbing.test.ts
+++ b/apps/desktop/src/main/remote-agent/__tests__/plumbing.test.ts
@@ -163,6 +163,9 @@ describe('wire payloads', () => {
const base = { sessionId: 's1', options: { model: 'm' }, workspace: { workingDir: '/p', platform: 'darwin' } };
expect(decodeOpenPayload({ ...base, groupAssigned: true }).groupAssigned).toBe(true);
expect(decodeOpenPayload({ ...base, groupAssigned: 'yes' })).not.toHaveProperty('groupAssigned');
+ // 组所在电脑替受邀者中转的任务带不透明的 relay 键;格式不对丢弃。
+ expect(decodeOpenPayload({ ...base, relay: 'a1b2c3d4e5f60718293a4b5c6d7e8f90' }).relay).toBe('a1b2c3d4e5f60718293a4b5c6d7e8f90');
+ expect(decodeOpenPayload({ ...base, relay: '../x' })).not.toHaveProperty('relay');
expect(() => decodeOpenPayload({ sessionId: 's', options: { model: 'm' }, workspace: { workingDir: '/p', platform: 'beos' } })).toThrow();
});
diff --git a/apps/desktop/src/main/remote-agent/__tests__/poll.test.ts b/apps/desktop/src/main/remote-agent/__tests__/poll.test.ts
index 94e8b15745..c191497e11 100644
--- a/apps/desktop/src/main/remote-agent/__tests__/poll.test.ts
+++ b/apps/desktop/src/main/remote-agent/__tests__/poll.test.ts
@@ -14,7 +14,7 @@ interface FakeRun {
}
/** 与 runHost 的 poll 同一套语义的最小被控端(只关心事件流)。 */
-function fakeHost() {
+function fakeHost(maxWaitMs = 200) {
const runs = new Map<string, FakeRun>();
const calls: Array<{ runs: Array<{ runId: string; cursor: number }>; waitMs?: number }> = [];
let failNext: Error | null = null;
@@ -44,7 +44,7 @@ function fakeHost() {
const ready = live.length < request.runs.length || live.some(({ run, cursor }) => run.log.isReady(cursor));
if (!ready && (request.waitMs ?? 0) > 0) {
await new Promise<void>((resolve) => {
- const timer = setTimeout(finish, Math.min(request.waitMs ?? 0, 200));
+ const timer = setTimeout(finish, Math.min(request.waitMs ?? 0, maxWaitMs));
const offs = live.map(({ run }) => run.log.onChange(finish));
function finish() {
clearTimeout(timer);
@@ -112,6 +112,30 @@ afterEach(() => {
});
describe('multiplexed poll', () => {
+ it('keeps pulling a run registered during a long wait, without waiting for the old poll to time out', async () => {
+ // 被控端照实挂满等待时间:旧的长等待只覆盖第一个任务。
+ const host = fakeHost(10_000);
+ const poller = new RemoteAgentPoller((args) => host.invoke(args));
+ const first = randomUUID();
+ const second = randomUUID();
+ host.add(first).append({ step: 'started' });
+ const firstSink = collector(first);
+ poller.register(firstSink.run);
+ await until(() => firstSink.text().includes('started'));
+ const secondLog = host.add(second);
+ const secondSink = collector(second);
+ poller.register(secondSink.run);
+ secondLog.append({ step: 'projection' });
+ await until(() => secondSink.text().includes('projection'));
+ const startedAt = Date.now();
+ secondLog.append({ step: 'started' });
+ await until(() => secondSink.text().includes('"started"'), 2_000);
+ expect(Date.now() - startedAt).toBeLessThan(1_000);
+ host.runs.get(first)!.log.end();
+ secondLog.end();
+ await until(() => firstSink.done && secondSink.done);
+ });
+
it('delivers every run exactly once with at most two polls in flight', async () => {
const host = fakeHost();
let inflight = 0;
diff --git a/apps/desktop/src/main/remote-agent/controller/poller.ts b/apps/desktop/src/main/remote-agent/controller/poller.ts
index c23db2d3e2..761eaf1398 100644
--- a/apps/desktop/src/main/remote-agent/controller/poller.ts
+++ b/apps/desktop/src/main/remote-agent/controller/poller.ts
@@ -74,6 +74,8 @@ export class RemoteAgentPoller {
private retryTimer: ReturnType<typeof setTimeout> | null = null;
private rotation = 0;
private emptyFastStreak = 0;
+ /** 在途的 poll 各自覆盖哪些任务(判断有没有任务没人在拉)。 */
+ private readonly inflightCoverage = new Set<ReadonlySet<string>>();
constructor(
readonly invoke: RemoteAgentInvoke,
@@ -117,7 +119,9 @@ export class RemoteAgentPoller {
private async pollOnce(): Promise<void> {
const wanted = this.snapshot();
const startedAt = this.now();
+ const coverage: ReadonlySet<string> = new Set(wanted.map((item) => item.runId));
this.inflight += 1;
+ this.inflightCoverage.add(coverage);
let raw: unknown;
let failure: unknown = null;
try {
@@ -126,6 +130,7 @@ export class RemoteAgentPoller {
failure = error;
} finally {
this.inflight -= 1;
+ this.inflightCoverage.delete(coverage);
}
let result: RemoteAgentPollResult | null = null;
if (!failure) {
@@ -160,11 +165,26 @@ export class RemoteAgentPoller {
}
private ensureAfterReturn(): void {
- // 这个 poll 回来了:没有其它在途的就再发一个;有任务没被覆盖时也发。
- if (this.inflight === 0) this.needFresh = true;
+ // 这个 poll 回来了:没有其它在途的就再发一个;有任务没被仍在途的 poll 覆盖时也发——否则新登记的
+ // 任务在覆盖它的那个 poll 带回第一段数据后,要等旧的长等待超时(最长 READ_WAIT_MS)才有人再拉它。
+ if (this.inflight === 0 || this.hasUncoveredRun()) this.needFresh = true;
this.ensure();
}
+ private hasUncoveredRun(): boolean {
+ for (const runId of this.entries.keys()) {
+ let covered = false;
+ for (const coverage of this.inflightCoverage) {
+ if (coverage.has(runId)) {
+ covered = true;
+ break;
+ }
+ }
+ if (!covered) return true;
+ }
+ return false;
+ }
+
/** 处理一次 poll 的结果;返回是否交付了任何新数据或状态变化。 */
private apply(wanted: ReadonlyArray<{ runId: string; cursor: number }>, result: RemoteAgentPollResult): boolean {
const requested = new Map(wanted.map((item) => [item.runId, item.cursor]));
diff --git a/apps/desktop/src/main/remote-agent/controller/service.ts b/apps/desktop/src/main/remote-agent/controller/service.ts
index cbe0271383..3460904ffb 100644
--- a/apps/desktop/src/main/remote-agent/controller/service.ts
+++ b/apps/desktop/src/main/remote-agent/controller/service.ts
@@ -95,20 +95,35 @@ async function isGitRepo(workingDir: string): Promise<boolean> {
return false;
}
+/**
+ * 每台电脑一个拉取器:那台上的全部任务共用一个 poll,不挤占设备互联的其它请求。本机作为控制端的任务
+ * 与供应商组替受邀者中转的任务(remote-agent/host 的 groupRelay)共用同一份,同一台电脑只占一个长等待。
+ * 空闲的拉取器不发任何请求,同账号电脑数量有限,留着复用。
+ */
+const sharedPollers = new WeakMap<DeviceAgentServiceDeps['remoteInvoke'], Map<string, RemoteAgentPoller>>();
+
+export function remoteAgentPollerFor(
+ deviceId: string,
+ remoteInvoke: DeviceAgentServiceDeps['remoteInvoke'],
+ log?: { warn(message: string, meta?: Record<string, unknown>): void },
+): RemoteAgentPoller {
+ let byDevice = sharedPollers.get(remoteInvoke);
+ if (!byDevice) {
+ byDevice = new Map();
+ sharedPollers.set(remoteInvoke, byDevice);
+ }
+ let poller = byDevice.get(deviceId);
+ if (!poller) {
+ poller = new RemoteAgentPoller(remoteAgentInvoker(deviceId, remoteInvoke), log);
+ byDevice.set(deviceId, poller);
+ }
+ return poller;
+}
+
/** Maker 的 startDeviceAgentSession 实现。 */
export function createDeviceAgentStarter(deps: DeviceAgentServiceDeps) {
const log = deps.logger.child('remote-agent');
- // 每台电脑一个拉取器:那台上的全部任务共用一个 poll,不挤占设备互联的其它请求。
- const pollers = new Map<string, RemoteAgentPoller>();
- // 空闲的拉取器不发任何请求,同账号电脑数量有限,留着复用。
- const pollerFor = (deviceId: string): RemoteAgentPoller => {
- let poller = pollers.get(deviceId);
- if (!poller) {
- poller = new RemoteAgentPoller(remoteAgentInvoker(deviceId, deps.remoteInvoke), log);
- pollers.set(deviceId, poller);
- }
- return poller;
- };
+ const pollerFor = (deviceId: string): RemoteAgentPoller => remoteAgentPollerFor(deviceId, deps.remoteInvoke, log);
return async (input: { agentKind: AgentKind; deviceId: string; options: StartSessionOptions }): Promise<AgentSessionHandle> => {
const opts: StartSessionOptions = { ...input.options };
const poller = pollerFor(input.deviceId);
diff --git a/apps/desktop/src/main/remote-agent/host/groupRelay.ts b/apps/desktop/src/main/remote-agent/host/groupRelay.ts
new file mode 100644
index 0000000000..ad6c853dc1
--- /dev/null
+++ b/apps/desktop/src/main/remote-agent/host/groupRelay.ts
@@ -0,0 +1,60 @@
+/**
+ * 供应商组替受邀者中转任务的纯函数部分(docs/product-rules/provider-groups.md §4、§8、§9)。
+ *
+ * 组所在电脑(本机)把受邀者的任务交给组内电脑运行时:
+ * - 受邀者在组内电脑上的身份是本机为它取的不透明键(relay),不带分享与成员信息;
+ * - 受邀者的任务 id 换成按(受邀者, 任务 id)派生的 id,两个受邀者用同一个 id 也不会在组内电脑上撞车;
+ * - 组内电脑报出的、会透露它是谁或它与本机关系的错误,换成中性的「暂时不可用」;
+ * - 启动阶段换电脑时,每次尝试的 WebSocket 连接编号加前缀,不同尝试的连接不会混在一起。
+ */
+import { createHash } from 'node:crypto';
+
+import type { RemoteAgentErrorInfo } from '@cindy/device-link';
+
+/** 受邀者在组内电脑上的不透明键(32 位十六进制)。 */
+export function relayKeyFor(guestController: string): string {
+ return createHash('sha256').update(`provider-group-relay\0${guestController}`).digest('hex').slice(0, 32);
+}
+
+/** 受邀者任务在组内电脑上的任务 id。 */
+export function relaySessionIdFor(guestController: string, sessionId: string): string {
+ return `g${createHash('sha256').update(`${guestController}\0${sessionId}`).digest('hex').slice(0, 40)}`;
+}
+
+/**
+ * 组内电脑那边的路径类错误(那台对本机的分享暂停 / 删除、没开远程调用、换了账号、太旧、连不上、太忙)
+ * 对受邀者没有意义,还会透露组内电脑与本机的关系:统一成「暂时不可用」。Agent 本身的报错(用量上限等)
+ * 在事件流里,不经过这里。
+ */
+const LOCATION_CODES = /^REMOTE_AGENT_(?:SHARE_PAUSED|SHARE_REMOVED|SHARE_UNAVAILABLE|PROVIDER_NOT_ALLOWED|ACCOUNT_CHANGED|PEER_TOO_OLD|DEVICE_UNREACHABLE|BUSY|UNAVAILABLE)$|^(?:ACCESS_REVOKED|REMOTE_DISABLED|CHANNEL_NOT_ALLOWED|UNSUPPORTED_CAPABILITY|DEVICE_OFFLINE|PEER_RESET|TIMEOUT|INVOKE_TIMEOUT|LINK_CLOSED|LINK_NOT_OPEN|NOT_CONNECTED)$/;
+
+export const RELAY_UNAVAILABLE_ERROR: RemoteAgentErrorInfo = {
+ code: 'REMOTE_AGENT_UNAVAILABLE',
+ message: '[REMOTE_AGENT_UNAVAILABLE] The computer running this task is not available right now.',
+};
+
+export function relayErrorForGuest(info: RemoteAgentErrorInfo | undefined): RemoteAgentErrorInfo | undefined {
+ if (!info) return undefined;
+ const code = /^\[([A-Z][A-Z0-9_]+)\]/.exec(info.message)?.[1] ?? info.code;
+ return LOCATION_CODES.test(code) ? { ...RELAY_UNAVAILABLE_ERROR } : info;
+}
+
+export function relayErrorInfoFrom(error: unknown): RemoteAgentErrorInfo {
+ const err = error instanceof Error ? error : new Error(String(error));
+ const rawCode = (err as unknown as { code?: unknown }).code;
+ const code = /^\[([A-Z][A-Z0-9_]+)\]/.exec(err.message)?.[1]
+ ?? (typeof rawCode === 'string' && rawCode ? rawCode : 'AGENT_ERROR');
+ const info: RemoteAgentErrorInfo = { code: code.slice(0, 128), message: err.message.slice(0, 2048), name: err.name };
+ return relayErrorForGuest(info) ?? info;
+}
+
+/** 第 attempt 次启动尝试的 WebSocket 连接编号(受邀者看到的)。 */
+export function relayConnId(attempt: number, connId: string): string {
+ return `r${attempt}-${connId}`.slice(0, 64);
+}
+
+/** 受邀者推来的帧属于哪次尝试的哪条连接;不是当前尝试的返回 null(丢弃)。 */
+export function relayMemberConnId(attempt: number, guestConnId: string): string | null {
+ const prefix = `r${attempt}-`;
+ return guestConnId.startsWith(prefix) ? guestConnId.slice(prefix.length) : null;
+}
diff --git a/apps/desktop/src/main/remote-agent/host/runHost.ts b/apps/desktop/src/main/remote-agent/host/runHost.ts
index bf31f0f1c0..02ce95e820 100644
--- a/apps/desktop/src/main/remote-agent/host/runHost.ts
+++ b/apps/desktop/src/main/remote-agent/host/runHost.ts
@@ -44,8 +44,17 @@ import {
} from '@cindy/device-link';
import type { AgentEvent, AgentSessionHandle, InteractionRequest } from '@cindy/maker-core';
+import { RemoteAgentRunClient, type RemoteAgentInvoke, type RemoteAgentPoller } from '../controller/runClient';
import { EventLog, waitForAny } from '../eventLog';
import { createGuestUsageMeter, type GuestUsageSample } from './guestUsage';
+import {
+ relayConnId,
+ relayErrorForGuest,
+ relayErrorInfoFrom,
+ relayKeyFor,
+ relayMemberConnId,
+ relaySessionIdFor,
+} from './groupRelay';
import { projectPathText } from '../executor/workspace';
import {
MAX_ANCESTOR_LEVELS,
@@ -75,6 +84,13 @@ export const REMOTE_AGENT_HOST_UNREAD_BYTES = 64 * 1024 * 1024;
export const REMOTE_AGENT_HOST_IDLE_MS = 3 * 60_000;
/** 结束后保留一段时间供控制端读完收尾事件。 */
export const REMOTE_AGENT_HOST_RETAIN_MS = 60_000;
+/**
+ * 供应商组的组所在电脑替多个受邀者中转过来时,同一个控制端在本机的任务按受邀者(relay)各算
+ * REMOTE_AGENT_MAX_RUNS_PER_CONTROLLER;这个控制端合计不超过这里。
+ */
+export const REMOTE_AGENT_MAX_RELAYED_RUNS_PER_CONTROLLER = REMOTE_AGENT_MAX_RUNS_PER_CONTROLLER * 4;
+/** 受邀者的任务交给组内电脑时,启动阶段最多换几台。 */
+const MAX_RELAY_START_ATTEMPTS = 8;
const UPLOAD_IDLE_MS = 2 * 60_000;
const MAX_STAGED_BYTES_PER_CONTROLLER = REMOTE_AGENT_MAX_PAYLOAD_BYTES * 2;
const MAX_DECOMPRESSED_BYTES = 128 * 1024 * 1024;
@@ -163,6 +179,11 @@ export interface RemoteAgentHostDeps {
providerId: string;
isCurrent(): boolean;
}): Promise<GuestProviderRouteBinding | null>;
+ /**
+ * 供应商组(本机是组所在电脑,docs/product-rules/provider-groups.md §4):受邀者的新任务按组策略交给
+ * 组内电脑运行,本机中转。不提供 = 受邀者的任务一律在本机运行(现有接线)。
+ */
+ groupRelay?: RemoteAgentGroupRelayDeps;
captureOwner(): unknown;
isOwnerCurrent(owner: unknown): boolean;
/** 本机存放影子目录与附件的根目录。 */
@@ -174,6 +195,50 @@ export interface RemoteAgentHostDeps {
};
}
+/** 受邀者任务交给的组内电脑(组所在电脑视角)。 */
+export interface GroupRelayMember {
+ memberKey: string;
+ agentDeviceId: string;
+ /** 那台电脑上这个供应商的 id。 */
+ providerId: string;
+ /** 同账号电脑:要求它声明 guestRelay(按受邀者隔离)。分享来的电脑本来就把本机当受邀者。 */
+ sameAccount: boolean;
+}
+
+export type GroupRelayPlan =
+ /** 组里选中了本机。 */
+ | { kind: 'local' }
+ | ({ kind: 'member' } & GroupRelayMember)
+ /** 组里没有能接这个任务的电脑。 */
+ | { kind: 'unavailable' };
+
+export interface RemoteAgentGroupRelayDeps {
+ /** 受邀者的新任务该交给谁;这个供应商没有组返回 null(照常在本机运行)。 */
+ plan(input: { kind: RemoteAgentKind; model: string; providerId: string; exclude: ReadonlySet<string> }): Promise<GroupRelayPlan | null>;
+ /** 经设备互联连某台组内电脑的远程 Agent 通道(与本机作为控制端共用拉取器)。 */
+ connect(agentDeviceId: string): { invoke: RemoteAgentInvoke; poller: RemoteAgentPoller };
+ /** 那台在启动阶段没能接下任务(连不上、登录失效等):按组的口径冷却。 */
+ noteStartFailure(providerId: string, member: GroupRelayMember, error: unknown): void;
+ /** 计入那台组内电脑的负载(按它是否正在运行一轮)。 */
+ trackRun(providerId: string, memberKey: string): { setRunning(running: boolean): void; release(): void };
+ /** 删掉受邀者后,请接过它任务的组内电脑清掉留下的会话记录与目录。 */
+ forget(agentDeviceId: string, relay: string): Promise<void>;
+}
+
+/** 本机作为组所在电脑把受邀者的任务转给组内电脑时的后端(代替本机的 Agent 会话)。 */
+interface RelayBackend {
+ client: RemoteAgentRunClient;
+ member: GroupRelayMember;
+ /** 第几次启动尝试(WebSocket 连接编号的前缀)。 */
+ attempt: number;
+ /** 那台已经开始运行(启动阶段失败才能换下一台)。 */
+ started: boolean;
+ /** 推帧按任务串行,保证 Codex exec-server 帧的顺序。 */
+ pushChain: Promise<void>;
+ model?: string;
+ load: { setRunning(running: boolean): void; release(): void };
+}
+
interface Upload {
controller: string;
chunks: Array<Buffer | undefined>;
@@ -216,6 +281,13 @@ interface Run {
usageMeter?: ReturnType<typeof createGuestUsageMeter>;
lastState?: string;
stateTimer?: ReturnType<typeof setInterval>;
+ /**
+ * 组所在电脑替受邀者中转过来的任务(本机是组内电脑):组所在电脑为这个受邀者取的键。按受邀者隔离,
+ * 会话索引、受邀者目录与运行数都按(控制端, relay)分开。
+ */
+ relayKey?: string;
+ /** 本机是组所在电脑、把这个受邀者任务转给了组内电脑。 */
+ relay?: RelayBackend;
}
/** 控制端真实路径 → 影子目录里逐级镜像的目录名(去掉本机文件系统不允许的字符)。 */
@@ -345,8 +417,14 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
const trustOf = (controller: string): RemoteAgentControllerTrust => deps.controllerTrust?.(controller) ?? 'owner';
/** 按控制端分开存放的目录名(影子工作区、附件与受邀者目录)。 */
const controllerDir = (controller: string) => createHash('sha256').update(controller).digest('hex').slice(0, 16);
- /** 受邀者目录:Codex / Pi 的会话历史与 Codex 的运行目录,按控制端跨任务保留,清理时整体删除。 */
- const guestHomeFor = (controller: string) => path.join(deps.runsRoot, 'guest-homes', controllerDir(controller));
+ /**
+ * 受邀者隔离的作用域:一般就是控制端;组所在电脑替受邀者中转过来的任务再按 relay 分开(同一个组所在
+ * 电脑替不同受邀者中转,彼此不能接回对方的会话、不共用受邀者目录)。
+ */
+ const guestScopeOf = (controller: string, relay: string | undefined) =>
+ (relay ? `${controller}\0relay:${relay}` : controller);
+ /** 受邀者目录:Codex / Pi 的会话历史与 Codex 的运行目录,按作用域跨任务保留,清理时整体删除。 */
+ const guestHomeFor = (scope: string) => path.join(deps.runsRoot, 'guest-homes', controllerDir(scope));
/**
* 受邀者在本机建立过的会话:恢复与分叉只能接回自己的会话(不能凭 id 接上本机用户自己的
@@ -355,14 +433,32 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
interface GuestSessionRecord {
/** 控制端 key(供应商分享的本地 peer key,含分享与成员,不是秘密),按成员清理时据此匹配。 */
controller: string;
+ /** 组所在电脑替受邀者中转过来的任务:那个受邀者的 relay 键。 */
+ relay?: string;
hostSessionIds: string[];
nativeIds: string[];
+ /**
+ * 本机是组所在电脑、把这个受邀者的任务转给了组内电脑:原生会话 id → 在哪台。续接只能回到那台
+ * (会话记录在那里);那台被移出组后也照样回到那台。
+ */
+ members?: Record<string, GroupRelayMember>;
}
const guestIndexFile = path.join(deps.runsRoot, 'guest-sessions.json');
- const guestDigest = (controller: string) => createHash('sha256').update(controller).digest('hex').slice(0, 32);
+ const guestDigest = (scope: string) => createHash('sha256').update(scope).digest('hex').slice(0, 32);
let guestIndex: Promise<Map<string, GuestSessionRecord>> | null = null;
let guestIndexWrite: Promise<void> = Promise.resolve();
+ function readRelayMembers(value: unknown): Record<string, GroupRelayMember> | undefined {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+ const out: Record<string, GroupRelayMember> = {};
+ for (const [nativeId, raw] of Object.entries(value as Record<string, unknown>)) {
+ const item = raw as Partial<GroupRelayMember> | null;
+ if (!item || typeof item.memberKey !== 'string' || typeof item.agentDeviceId !== 'string' || typeof item.providerId !== 'string') continue;
+ out[nativeId] = { memberKey: item.memberKey, agentDeviceId: item.agentDeviceId, providerId: item.providerId, sameAccount: item.sameAccount === true };
+ }
+ return Object.keys(out).length ? out : undefined;
+ }
+
function loadGuestIndex(): Promise<Map<string, GuestSessionRecord>> {
guestIndex ??= fsp.readFile(guestIndexFile, 'utf8')
.then((raw) => {
@@ -371,7 +467,14 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
for (const [digest, record] of Object.entries(parsed)) {
const list = (value: unknown) => (Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []);
if (typeof record?.controller !== 'string') continue;
- map.set(digest, { controller: record.controller, hostSessionIds: list(record?.hostSessionIds), nativeIds: list(record?.nativeIds) });
+ const members = readRelayMembers(record.members);
+ map.set(digest, {
+ controller: record.controller,
+ ...(typeof record.relay === 'string' ? { relay: record.relay } : {}),
+ hostSessionIds: list(record?.hostSessionIds),
+ nativeIds: list(record?.nativeIds),
+ ...(members ? { members } : {}),
+ });
}
return map;
})
@@ -391,10 +494,16 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
return guestIndexWrite;
}
- async function recordGuestSession(controller: string, hostSessionId: string, nativeIds: ReadonlyArray<string | undefined>): Promise<void> {
+ async function recordGuestSession(
+ controller: string,
+ relay: string | undefined,
+ hostSessionId: string,
+ nativeIds: ReadonlyArray<string | undefined>,
+ member?: GroupRelayMember,
+ ): Promise<void> {
const map = await loadGuestIndex();
- const digest = guestDigest(controller);
- const record = map.get(digest) ?? { controller, hostSessionIds: [], nativeIds: [] };
+ const digest = guestDigest(guestScopeOf(controller, relay));
+ const record = map.get(digest) ?? { controller, ...(relay ? { relay } : {}), hostSessionIds: [], nativeIds: [] };
let changed = !map.has(digest);
if (!record.hostSessionIds.includes(hostSessionId)) {
record.hostSessionIds.push(hostSessionId);
@@ -405,15 +514,25 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
record.nativeIds.push(id);
changed = true;
}
+ if (id && member && record.members?.[id]?.memberKey !== member.memberKey) {
+ record.members = { ...record.members, [id]: { ...member } };
+ changed = true;
+ }
}
if (!changed) return;
map.set(digest, record);
await persistGuestIndex(map);
}
- async function guestOwnsSession(controller: string, nativeId: string): Promise<boolean> {
+ async function guestOwnsSession(controller: string, relay: string | undefined, nativeId: string): Promise<boolean> {
const map = await loadGuestIndex();
- return map.get(guestDigest(controller))?.nativeIds.includes(nativeId) ?? false;
+ return map.get(guestDigest(guestScopeOf(controller, relay)))?.nativeIds.includes(nativeId) ?? false;
+ }
+
+ /** 组所在电脑:受邀者的这个会话当初转给了哪台组内电脑;在本机运行的返回 null。 */
+ async function relayMemberOf(controller: string, nativeId: string): Promise<GroupRelayMember | null> {
+ const map = await loadGuestIndex();
+ return map.get(guestDigest(controller))?.members?.[nativeId] ?? null;
}
function withShadowLock<T>(hostSessionId: string, fn: () => Promise<T>): Promise<T> {
@@ -505,7 +624,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
append(run, { t: 'state', state });
// 会话 id 可能在任务中途换新(清空上下文等),受邀者能恢复的会话随之登记。
if (run.trust === 'guest' && run.hostSessionId) {
- void recordGuestSession(run.controller, run.hostSessionId, [
+ void recordGuestSession(run.controller, run.relayKey, run.hostSessionId, [
typeof state.id === 'string' ? state.id : undefined,
typeof state.requestSessionId === 'string' ? state.requestSessionId : undefined,
]);
@@ -685,13 +804,14 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
async function startRun(run: Run, payload: RemoteAgentOpenPayload): Promise<void> {
try {
- const hostSessionId = hostSessionIdFor(run.controller, payload.sessionId);
+ // 中转过来的任务按(控制端, relay)派生:不同受邀者即使任务 id 相同也不会共用本机侧任务。
+ const hostSessionId = hostSessionIdFor(guestScopeOf(run.controller, run.relayKey), payload.sessionId);
run.hostSessionId = hostSessionId;
let guestHome: string | undefined;
if (run.trust === 'guest') {
// 先登记再启动:启动中途失败时,受邀者目录与会话记录也能在分享删除时被找到并清理。
- await recordGuestSession(run.controller, hostSessionId, []);
- guestHome = guestHomeFor(run.controller);
+ await recordGuestSession(run.controller, run.relayKey, hostSessionId, []);
+ guestHome = guestHomeFor(guestScopeOf(run.controller, run.relayKey));
await fsp.mkdir(guestHome, { recursive: true, mode: 0o700 });
}
const { shadowDir, mirrorRoot, sessionRoot, extraDirs, writableDirs, projectText } = await withShadowLock(hostSessionId, async () => {
@@ -767,7 +887,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
return;
}
run.handle = handle;
- if (run.trust === 'guest') await recordGuestSession(run.controller, hostSessionId, [handle.id, handle.requestSessionId]);
+ if (run.trust === 'guest') await recordGuestSession(run.controller, run.relayKey, hostSessionId, [handle.id, handle.requestSessionId]);
handle.setInteractionResolver(async (request: InteractionRequest) => {
const reply = await reverse(run, { type: 'interaction', request });
if (reply.type === 'interaction') return reply.result as Awaited<ReturnType<Parameters<AgentSessionHandle['setInteractionResolver']>[0]>>;
@@ -788,7 +908,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
try {
for await (const event of handle.events()) {
if (run.closing) break;
- if (run.trust === 'guest') meterGuestUsage(run, handle, event);
+ if (run.trust === 'guest') meterGuestUsage(run, handle.model, event);
append(run, { t: 'event', event });
emitState(run);
}
@@ -799,17 +919,183 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
}
}
- function meterGuestUsage(run: Run, handle: AgentSessionHandle, event: AgentEvent): void {
+ function meterGuestUsage(run: Run, model: string | undefined, event: AgentEvent): void {
if (!deps.recordGuestUsage || event.type !== 'done') return;
run.usageMeter ??= createGuestUsageMeter(run.kind);
try {
- const samples = run.usageMeter.observe(event, handle.model);
+ const samples = run.usageMeter.observe(event, model ?? '');
if (samples.length > 0) deps.recordGuestUsage(run.controller, { kind: run.kind, providerId: run.providerId ?? null, samples });
} catch (error) {
deps.log?.warn('remote agent guest usage record failed', { runId: run.id, error: String(error) });
}
}
+ // ─── 供应商组:本机是组所在电脑,把受邀者的任务转给组内电脑 ─────────────────
+
+ /** 转给组内电脑的打开载荷:已按受邀者复核过;来源换成那台上的供应商,带防转圈标记与受邀者的 relay 键。 */
+ function relayedOpenPayload(run: Run, payload: RemoteAgentOpenPayload, member: GroupRelayMember): RemoteAgentOpenPayload {
+ return {
+ ...payload,
+ sessionId: relaySessionIdFor(run.controller, payload.sessionId),
+ groupAssigned: true,
+ relay: relayKeyFor(run.controller),
+ options: { ...payload.options, providerId: member.providerId },
+ };
+ }
+
+ /**
+ * 启动中转任务。全新任务在那台没接下(还没开始运行)时换组里下一台,受邀者无感;续接只能回到原来那台。
+ * 组里选回本机时改在本机运行。
+ */
+ async function startRelay(
+ run: Run,
+ payload: RemoteAgentOpenPayload,
+ first: GroupRelayMember,
+ options: { fresh: boolean },
+ ): Promise<void> {
+ const relayDeps = deps.groupRelay!;
+ const groupProviderId = run.providerId!;
+ const tried = new Set<string>();
+ let member: GroupRelayMember | null = first;
+ let lastError: unknown = null;
+ for (let attempt = 1; member && attempt <= MAX_RELAY_START_ATTEMPTS && !run.closing; attempt += 1) {
+ const current: GroupRelayMember = member;
+ member = null;
+ const connection = relayDeps.connect(current.agentDeviceId);
+ const load = relayDeps.trackRun(groupProviderId, current.memberKey);
+ const backend: RelayBackend = {
+ client: undefined as unknown as RemoteAgentRunClient,
+ member: current,
+ attempt,
+ started: false,
+ pushChain: Promise.resolve(),
+ load,
+ };
+ const wsOpened = new Set<string>();
+ backend.client = new RemoteAgentRunClient(randomUUID(), connection.poller, {
+ onEvent: (event) => {
+ if (run.closing || run.relay !== backend) return;
+ meterGuestUsage(run, backend.model, event as AgentEvent);
+ append(run, { t: 'event', event });
+ },
+ onState: (state) => {
+ if (run.closing || run.relay !== backend) return;
+ const projection = state.workspaceProjection as { mirrorRoot?: unknown } | undefined;
+ if (typeof projection?.mirrorRoot === 'string') run.virtualRoot = projection.mirrorRoot;
+ if (typeof state.model === 'string') backend.model = state.model;
+ if (typeof state.turnRunning === 'boolean') backend.load.setRunning(state.turnRunning);
+ if (run.hostSessionId) {
+ void recordGuestSession(run.controller, undefined, run.hostSessionId, [
+ typeof state.id === 'string' ? state.id : undefined,
+ typeof state.requestSessionId === 'string' ? state.requestSessionId : undefined,
+ ], current);
+ }
+ append(run, { t: 'state', state });
+ },
+ onRequest: (request, signal) => reverse(run, request, signal),
+ onWs: (item) => {
+ if (run.closing || run.relay !== backend) return;
+ const connId = relayConnId(attempt, item.connId);
+ if (item.kind === 'open') wsOpened.add(connId);
+ append(run, { ...item, connId });
+ },
+ onClosed: (reason, error) => {
+ // 启动阶段的收尾由下面的 catch 处理(可能换下一台);开始运行之后那台结束了,这个任务也结束。
+ if (run.relay !== backend || run.closing || !backend.started) return;
+ run.log.append({ t: 'closed', reason, ...(error ? { error: relayErrorForGuest(error) } : {}) });
+ void finishRun(run, reason, 'navigation', false, true);
+ },
+ }, randomUUID, deps.log);
+ run.relay = backend;
+ try {
+ const caps = await RemoteAgentRunClient.caps(connection.invoke);
+ if (caps.virtualWorkspace !== true || (current.sameAccount && caps.guestRelay !== true)) {
+ throw new Error('[REMOTE_AGENT_PEER_TOO_OLD] the computer in the provider group cannot take shared tasks yet');
+ }
+ const started = await backend.client.open(run.kind, relayedOpenPayload(run, payload, current));
+ if (run.closing) {
+ await backend.client.close('close', 'navigation').catch(() => undefined);
+ return;
+ }
+ backend.started = true;
+ append(run, { t: 'started', handle: started });
+ const nativeIds = [started.id, started.requestSessionId].map((id) => (typeof id === 'string' ? id : undefined));
+ if (run.hostSessionId) await recordGuestSession(run.controller, undefined, run.hostSessionId, nativeIds, current);
+ deps.log?.info('remote agent run relayed to the provider group', { runId: run.id, member: current.memberKey });
+ return;
+ } catch (error) {
+ lastError = error;
+ run.relay = undefined;
+ backend.client.abandon('start-failed');
+ load.release();
+ // 这次尝试里受邀者那边已经打开的连接全部关掉,下一次尝试的连接编号不同。
+ for (const connId of wsOpened) append(run, { t: 'ws', connId, kind: 'close' });
+ if (run.closing || !options.fresh) break;
+ tried.add(current.memberKey);
+ relayDeps.noteStartFailure(groupProviderId, current, error);
+ deps.log?.warn('remote agent: provider group computer did not take the shared task; trying the next one', {
+ runId: run.id,
+ member: current.memberKey,
+ error: String(error),
+ });
+ const next = await relayDeps.plan({
+ kind: run.kind,
+ model: payload.options.model,
+ providerId: groupProviderId,
+ exclude: tried,
+ }).catch(() => null);
+ if (next?.kind === 'local' && deps.isAgentAvailable(run.kind)) {
+ await startRun(run, payload);
+ return;
+ }
+ if (next?.kind === 'member') member = next;
+ }
+ }
+ if (run.closing) return;
+ append(run, { t: 'start-failed', error: relayErrorInfoFrom(lastError ?? new Error('[REMOTE_AGENT_UNAVAILABLE] no computer can run this task right now')) });
+ await finishRun(run, 'start-failed', 'navigation', false);
+ }
+
+ /** 受邀者对中转任务的方法调用:按受邀者复核后用同一个 callId 转给组内电脑;载荷不解码、不落盘。 */
+ async function relayCall(run: Run, relay: RelayBackend, callId: string, method: RemoteAgentMethod, payload: RemoteAgentPayload): Promise<void> {
+ try {
+ const raw = await resolvePayload(run.controller, payload);
+ const args = Array.isArray(raw) ? raw : [];
+ let callArgs: unknown[] = args;
+ if (method === 'setVendorOptions') callArgs = [sanitizeGuestVendorOptions(args[0])];
+ if (method === 'setExtraDirs') {
+ const library = confineGuestDirs([args[1]], run.virtualRoot)[0] ?? null;
+ callArgs = [confineGuestDirs(args[0], run.virtualRoot), library];
+ }
+ if (method === 'setWritableDirs') callArgs = [confineGuestDirs(args[0], run.virtualRoot)];
+ const access = deps.providerAccess;
+ if (access && method === 'send' && run.providerId && !access.isAllowed(run.providerId, run.controller)) {
+ failProviderNotAllowed();
+ }
+ if (method === 'setModel') {
+ // 来源钉在分享的供应商上(本机按分享的那个供应商核对模型),转给那台时换成那台上的这个供应商。
+ const opts = args[1] && typeof args[1] === 'object' && !Array.isArray(args[1]) ? args[1] as Record<string, unknown> : {};
+ if (access) {
+ const resolved = await access.resolve(run.kind, typeof args[0] === 'string' ? args[0] : '', run.providerId ?? null, run.controller);
+ if (!resolved) failProviderNotAllowed();
+ }
+ callArgs = [args[0], { ...opts, providerId: relay.member.providerId }, ...args.slice(2)];
+ }
+ const value = await relay.client.callWithId(callId, method, callArgs);
+ append(run, { t: 'result', callId, ok: true, ...(value !== undefined ? { value: JSON.parse(JSON.stringify(value)) } : {}) });
+ } catch (error) {
+ append(run, { t: 'result', callId, ok: false, error: relayErrorInfoFrom(error) });
+ } finally {
+ run.calls.set(callId, 'done');
+ if (run.calls.size > MAX_REMEMBERED_CALLS) {
+ for (const [id, status] of run.calls) {
+ if (run.calls.size <= MAX_REMEMBERED_CALLS) break;
+ if (status === 'done') run.calls.delete(id);
+ }
+ }
+ }
+ }
+
/** 结束任务:关掉 Agent 与隧道,拒掉未完成的反向请求,写收尾事件。 */
async function finishRun(
run: Run,
@@ -832,6 +1118,18 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
deps.log?.warn('remote agent close failed', { runId: run.id, error: String(error) });
}
}
+ // 中转任务:结束组内电脑上的那个任务(撤权、受邀者离开、关闭都走这里),并放掉它占的负载。
+ const relay = run.relay;
+ if (relay) {
+ if (closeHandle && !relay.client.isClosed) {
+ await relay.client.close(mode, teardown).catch((error) => {
+ deps.log?.warn('remote agent relay close failed', { runId: run.id, error: String(error) });
+ });
+ } else {
+ relay.client.abandon(reason);
+ }
+ relay.load.release();
+ }
// Agent 已关:撤销受邀者的出站登记,之后这条任务的请求一律被本机 proxy 拒绝。
run.guestRoute?.release();
run.guestRoute = undefined;
@@ -877,6 +1175,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
}
async function call(run: Run, callId: string, method: RemoteAgentMethod, payload: RemoteAgentPayload): Promise<void> {
+ if (run.relay?.started) return relayCall(run, run.relay, callId, method, payload);
const handle = run.handle;
try {
if (!handle) fail('REMOTE_AGENT_UNAVAILABLE', 'agent has not started');
@@ -1006,6 +1305,69 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
return out;
}
+ /**
+ * 结束并清理受邀者在本机留下的东西:任务、影子工作区与附件、受邀者目录、本机 Agent 目录里的会话记录。
+ * wholeController = 整个控制端都清(受邀者的分享删除);否则只清选中的作用域(组所在电脑请本机
+ * 忘掉某个受邀者,同一个控制端的其他任务不受影响)。本机是组所在电脑时,顺带请接过这个受邀者
+ * 任务的组内电脑也清掉。
+ */
+ async function purgeGuests(
+ runMatch: (run: Run) => boolean,
+ recordMatch: (record: GuestSessionRecord) => boolean,
+ wholeController: boolean,
+ ): Promise<void> {
+ const owned = [...runs.values()].filter(runMatch);
+ await Promise.all(owned.map((run) => finishRun(run, 'access-revoked', 'navigation')));
+ await Promise.all(owned.map((run) => disposeRun(run)));
+ const map = await loadGuestIndex();
+ const records = [...map.entries()].filter(([, record]) => recordMatch(record));
+ const scopes = new Set([
+ ...owned.map((run) => guestScopeOf(run.controller, run.relayKey)),
+ ...records.map(([, record]) => guestScopeOf(record.controller, record.relay)),
+ ]);
+ const controllers = wholeController
+ ? new Set([...owned.map((run) => run.controller), ...records.map(([, record]) => record.controller)])
+ : new Set<string>();
+ // 受邀者目录里是它的 Codex / Pi 会话历史;Windows 上刚退出的 Agent 可能还占着文件,重试几次。
+ const targets = [
+ ...[...controllers].flatMap((controller) => ['workspaces', 'attachments'].map((dir) => path.join(deps.runsRoot, dir, controllerDir(controller)))),
+ ...[...scopes].map((scope) => guestHomeFor(scope)),
+ ];
+ await Promise.all(targets.map((target) => (
+ fsp.rm(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }).catch(() => undefined)
+ )));
+ for (const [, record] of records) {
+ const devices = new Set(Object.values(record.members ?? {}).map((member) => member.agentDeviceId));
+ for (const agentDeviceId of devices) {
+ void deps.groupRelay?.forget(agentDeviceId, relayKeyFor(record.controller)).catch((error) => {
+ deps.log?.warn('remote agent: asking a provider group computer to forget a shared user failed', { error: String(error) });
+ });
+ }
+ }
+ if (!records.length) return;
+ try {
+ await deps.purgeHostedTranscripts?.(
+ records.flatMap(([, record]) => record.hostSessionIds),
+ records.flatMap(([, record]) => record.nativeIds),
+ );
+ } catch (error) {
+ // 留着登记,下次清理重试。
+ deps.log?.warn('remote agent transcript purge failed', { error: String(error) });
+ return;
+ }
+ for (const [digest] of records) map.delete(digest);
+ await persistGuestIndex(map);
+ }
+
+ /** 组所在电脑请本机忘掉它替某个受邀者中转过来的任务(只清调用方自己的 relay)。 */
+ function forgetRelay(controller: string, relay: string): Promise<void> {
+ return purgeGuests(
+ (run) => run.controller === controller && run.relayKey === relay,
+ (record) => record.controller === controller && record.relay === relay,
+ false,
+ );
+ }
+
async function handle(controller: string, raw: unknown, signal?: AbortSignal): Promise<unknown> {
const request = parseRemoteAgentRequest(raw);
if (!deps.isControllerAuthorized(controller)) fail('REMOTE_AGENT_UNAVAILABLE', 'remote control is not allowed');
@@ -1022,9 +1384,15 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
uploadChunkBytes: REMOTE_AGENT_UPLOAD_CHUNK_BYTES,
maxPayloadBytes: REMOTE_AGENT_MAX_PAYLOAD_BYTES,
virtualWorkspace: true,
+ // 能按受邀者隔离运行(供应商级授权与出站边界都已接上),才接受组所在电脑中转过来的受邀者任务。
+ ...(deps.providerAccess && deps.bindGuestProviderRoute ? { guestRelay: true } : {}),
};
return caps;
}
+ case 'forget':
+ // 组所在电脑删掉了某个受邀者:清掉替它运行过的任务。只作用于调用方自己的 relay。
+ await forgetRelay(controller, request.relay);
+ return {};
case 'upload': {
const uploadKey = key(controller, request.uploadId);
let upload = uploads.get(uploadKey);
@@ -1052,15 +1420,26 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
discardPayload(controller, request.payload);
return {};
}
- if (!deps.isAgentAvailable(request.agentKind)) fail('REMOTE_AGENT_UNSUPPORTED', `${request.agentKind} is not available on this computer`);
- const trust = trustOf(controller);
- if (trust === 'guest' && (!GUEST_SUPPORTED_AGENTS.has(request.agentKind) || !deps.providerAccess || !deps.bindGuestProviderRoute)) {
+ const controllerTrust = trustOf(controller);
+ const guestUnsupported = !GUEST_SUPPORTED_AGENTS.has(request.agentKind) || !deps.providerAccess || !deps.bindGuestProviderRoute;
+ if (controllerTrust === 'guest' && guestUnsupported) {
discardPayload(controller, request.payload);
fail('REMOTE_AGENT_UNSUPPORTED', `${request.agentKind} is not available to shared users on this computer`);
}
- const active = [...runs.values()].filter((run) => run.controller === controller && run.closedAt === undefined).length;
- if (active >= REMOTE_AGENT_MAX_RUNS_PER_CONTROLLER) fail('REMOTE_AGENT_BUSY', 'too many tasks are running from this computer');
let payload = decodeOpenPayload(await resolvePayload(controller, request.payload));
+ // 供应商组的组所在电脑替受邀者中转过来的任务:不论那台是不是同账号,都按受邀者隔离运行。
+ const relayKey = payload.relay;
+ const trust: RemoteAgentControllerTrust = relayKey ? 'guest' : controllerTrust;
+ if (relayKey && guestUnsupported) {
+ fail('REMOTE_AGENT_UNSUPPORTED', `${request.agentKind} is not available to shared users on this computer`);
+ }
+ // 运行数按受邀者作用域各算一份;同一控制端替多个受邀者中转时另有合计上限。
+ const active = [...runs.values()].filter((run) => run.controller === controller && run.closedAt === undefined);
+ const scope = guestScopeOf(controller, relayKey);
+ const scoped = active.filter((run) => guestScopeOf(run.controller, run.relayKey) === scope).length;
+ if (scoped >= REMOTE_AGENT_MAX_RUNS_PER_CONTROLLER || active.length >= REMOTE_AGENT_MAX_RELAYED_RUNS_PER_CONTROLLER) {
+ fail('REMOTE_AGENT_BUSY', 'too many tasks are running from this computer');
+ }
if (trust === 'guest') {
// 受邀者必须用虚拟工作区:本机 Agent 只看到会话目录内的路径,附加目录也映射在其中。
if (payload.virtualWorkspace !== true) {
@@ -1069,7 +1448,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
payload = sanitizeGuestOpenPayload(payload);
// 只能接回自己在本机建立过的会话:会话 id 不能用来接上本机用户自己的会话。
const resumeId = payload.options.resumeSessionId;
- if (resumeId && !(await guestOwnsSession(controller, resumeId))) {
+ if (resumeId && !(await guestOwnsSession(controller, relayKey, resumeId))) {
fail('REMOTE_AGENT_INVALID', 'this conversation cannot be resumed on this computer');
}
}
@@ -1086,12 +1465,37 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
providerId = resolved;
payload = { ...payload, options: { ...payload.options, providerId: resolved } };
}
+ // 供应商组(本机是组所在电脑):受邀者的任务按组分给组内电脑,本机中转。被中转过来的任务(带 relay)
+ // 与已由供应商组分配的任务(防转圈)直接在本机运行。续接只能回到当初运行它的那台。
+ let relayTo: GroupRelayMember | null = null;
+ if (controllerTrust === 'guest' && !relayKey && !payload.groupAssigned && deps.groupRelay && providerId) {
+ const resumeId = payload.options.resumeSessionId;
+ if (resumeId) {
+ relayTo = await relayMemberOf(controller, resumeId);
+ } else {
+ const plan = await deps.groupRelay.plan({
+ kind: request.agentKind,
+ model: payload.options.model,
+ providerId,
+ exclude: new Set(),
+ });
+ if (plan?.kind === 'unavailable') fail('REMOTE_AGENT_UNAVAILABLE', 'no computer can run this task right now');
+ if (plan?.kind === 'member') {
+ const { memberKey, agentDeviceId, providerId: memberProviderId, sameAccount } = plan;
+ relayTo = { memberKey, agentDeviceId, providerId: memberProviderId, sameAccount };
+ }
+ }
+ }
+ if (!relayTo && !deps.isAgentAvailable(request.agentKind)) {
+ fail('REMOTE_AGENT_UNSUPPORTED', `${request.agentKind} is not available on this computer`);
+ }
// 上面有等待:同一个 runId 的重发可能已经先登记了。
if (runs.has(key(controller, request.runId))) return {};
const run: Run = {
id: request.runId,
controller,
trust,
+ ...(relayKey ? { relayKey } : {}),
owner: deps.captureOwner(),
kind: request.agentKind,
log: new EventLog(REMOTE_AGENT_HOST_UNREAD_BYTES),
@@ -1107,8 +1511,20 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
};
runs.set(key(controller, request.runId), run);
ensureSweep();
- deps.log?.info('remote agent run opened', { runId: run.id, agent: run.kind });
- void startRun(run, payload);
+ deps.log?.info('remote agent run opened', { runId: run.id, agent: run.kind, ...(relayTo ? { relayed: true } : {}) });
+ if (relayTo) {
+ const member = relayTo;
+ // 先登记再中转:中转中途失败时,分享删除也能找到并清理(含通知那台组内电脑)。
+ run.hostSessionId = hostSessionIdFor(controller, payload.sessionId);
+ void recordGuestSession(controller, undefined, run.hostSessionId, [])
+ .then(() => startRelay(run, payload, member, { fresh: !payload.options.resumeSessionId }))
+ .catch(async (error) => {
+ append(run, { t: 'start-failed', error: relayErrorInfoFrom(error) });
+ await finishRun(run, 'start-failed', 'navigation', false);
+ });
+ } else {
+ void startRun(run, payload);
+ }
return {};
}
case 'call': {
@@ -1142,6 +1558,25 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
if (run.pushSeq.has(request.seq)) return {};
run.pushSeq.add(request.seq);
if (run.pushSeq.size > 1024) run.pushSeq.delete(run.pushSeq.values().next().value as number);
+ const relay = run.relay;
+ if (relay) {
+ // 中转任务:帧原样转给组内电脑(不拼接),按任务串行发出以保持顺序;只认当前这次启动尝试的连接。
+ const frames = request.frames.flatMap((frame) => {
+ const connId = relayMemberConnId(relay.attempt, frame.connId);
+ return connId ? [{ ...frame, connId }] : [];
+ });
+ if (frames.length) {
+ relay.pushChain = relay.pushChain
+ .then(() => relay.client.push(frames))
+ .catch((error) => {
+ deps.log?.warn('remote agent relay push failed', { runId: run.id, error: String(error) });
+ // 转发不上:两边都关掉这些连接,Agent 那边按连接断开处理。
+ for (const frame of frames) append(run, { t: 'ws', connId: relayConnId(relay.attempt, frame.connId), kind: 'close' });
+ void relay.client.push(frames.map((frame) => ({ connId: frame.connId, kind: 'close' as const }))).catch(() => undefined);
+ });
+ }
+ return {};
+ }
for (const frame of request.frames) {
if (frame.kind === 'message' && frame.data !== undefined) {
const joined = (run.pushParts.get(frame.connId) ?? '') + frame.data;
@@ -1188,33 +1623,7 @@ export function createRemoteAgentHost(deps: RemoteAgentHostDeps) {
* 附件,以及本机 Agent 目录里它们的会话记录。
*/
async purgeControllers(match: (controller: string) => boolean): Promise<void> {
- const owned = [...runs.values()].filter((run) => match(run.controller));
- await Promise.all(owned.map((run) => finishRun(run, 'access-revoked', 'navigation')));
- await Promise.all(owned.map((run) => disposeRun(run)));
- const map = await loadGuestIndex();
- const controllers = new Set([
- ...owned.map((run) => run.controller),
- ...[...map.values()].map((record) => record.controller).filter(match),
- ]);
- // 受邀者目录里是它的 Codex / Pi 会话历史;Windows 上刚退出的 Agent 可能还占着文件,重试几次。
- await Promise.all([...controllers].flatMap((controller) => ['workspaces', 'attachments', 'guest-homes'].map((dir) => (
- fsp.rm(path.join(deps.runsRoot, dir, controllerDir(controller)), { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
- .catch(() => undefined)
- ))));
- const records = [...map.entries()].filter(([, record]) => match(record.controller));
- if (!records.length) return;
- try {
- await deps.purgeHostedTranscripts?.(
- records.flatMap(([, record]) => record.hostSessionIds),
- records.flatMap(([, record]) => record.nativeIds),
- );
- } catch (error) {
- // 留着登记,下次清理重试。
- deps.log?.warn('remote agent transcript purge failed', { error: String(error) });
- return;
- }
- for (const [digest] of records) map.delete(digest);
- await persistGuestIndex(map);
+ await purgeGuests((run) => match(run.controller), (record) => match(record.controller), true);
},
/** 有进行中任务的控制端(分享管理页显示「几个任务运行中」)。 */
activeControllers(): string[] {
diff --git a/apps/desktop/src/main/remote-agent/host/service.ts b/apps/desktop/src/main/remote-agent/host/service.ts
index b6ff6aa790..1dd02e78f8 100644
--- a/apps/desktop/src/main/remote-agent/host/service.ts
+++ b/apps/desktop/src/main/remote-agent/host/service.ts
@@ -15,7 +15,12 @@ import {
type DataOwnerBroadcastScope,
} from '../../device-link/broadcast-tap.js';
import { setRemoteAgentHandler } from '../../device-link/dispatch.js';
+import { remoteBackgroundInvoke } from '../../device-link/index.js';
import { providerShareGuestAccess } from '../../device-link/providerShareHost.js';
+import { createProviderGroupGuestRelay } from '../../provider-group/guestRelay.js';
+import { getProviderGroupExternalLoad, getProviderGroupRouter } from '../../provider-group/runtime.js';
+import { readProviderGroup } from '../../provider-group/store.js';
+import { remoteAgentPollerFor } from '../controller/service';
import { getProviderShareUsageStore, installProviderShareUsageStore } from '../../device-link/providerShareUsageStore.js';
import { readDeviceLinkSettings } from '../../device-link/settings-store.js';
import { getDesktopProviderService } from '../../maker-host/createDesktopProviderService.js';
@@ -145,6 +150,18 @@ export function installRemoteAgentHost(options: { getMaker: () => Maker; userDat
const peer = parseProviderSharePeer(controller);
if (peer?.role === 'guest' && peer.memberId) usage.record(peer.shareId, peer.memberId, sample);
},
+ // 供应商组(本机是组所在电脑):受邀者的任务按组分给组内电脑,本机中转(provider-groups.md §4)。
+ groupRelay: createProviderGroupGuestRelay({
+ router: getProviderGroupRouter(),
+ readGroup: readProviderGroup,
+ externalLoad: getProviderGroupExternalLoad(),
+ connect: (agentDeviceId) => {
+ const poller = remoteAgentPollerFor(agentDeviceId, remoteBackgroundInvoke, log);
+ return { invoke: poller.invoke, poller };
+ },
+ now: () => Date.now(),
+ log,
+ }),
captureOwner: captureDataOwnerBroadcastScope,
isOwnerCurrent: (owner) => isDataOwnerBroadcastScopeCurrent(owner as DataOwnerBroadcastScope),
runsRoot: path.join(options.userDataDir, 'remote-agent'),
diff --git a/apps/desktop/src/main/remote-agent/wire.ts b/apps/desktop/src/main/remote-agent/wire.ts
index 038ab23719..f9b9b206b4 100644
--- a/apps/desktop/src/main/remote-agent/wire.ts
+++ b/apps/desktop/src/main/remote-agent/wire.ts
@@ -25,6 +25,7 @@ import {
type UserMessage,
} from '@cindy/maker-core';
import { projectAutoReviewUserReferences } from '@cindy/maker-shared/auto-review-intent';
+import { REMOTE_AGENT_RELAY_KEY_PATTERN } from '@cindy/device-link';
import {
channelForceConfirmMutatingToolCall,
@@ -148,6 +149,11 @@ export interface RemoteAgentOpenPayload {
* 不再进入这台自己的供应商组。可选字段,旧版本解码时丢弃(它本来没有组)。
*/
groupAssigned?: boolean;
+ /**
+ * 供应商组的组所在电脑替受邀者中转过来的任务:组所在电脑为这个受邀者取的不透明键。被控端按受邀者
+ * 隔离运行,会话记录与目录按(控制端, relay)分开。只发给 caps 声明了 guestRelay 的电脑。
+ */
+ relay?: string;
options: RemoteAgentWireStartOptions;
workspace: RemoteAgentWireWorkspace;
projectFiles: RemoteAgentWireFile[];
@@ -289,6 +295,7 @@ export function decodeOpenPayload(value: unknown): RemoteAgentOpenPayload {
sessionId,
...(value.virtualWorkspace === true ? { virtualWorkspace: true } : {}),
...(value.groupAssigned === true ? { groupAssigned: true } : {}),
+ ...(typeof value.relay === 'string' && REMOTE_AGENT_RELAY_KEY_PATTERN.test(value.relay) ? { relay: value.relay } : {}),
options: decodeStartOptions(value.options),
workspace: decodeWorkspace(value.workspace),
projectFiles,
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 8a2e1f02b5..d5ff59e6bf 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -733,6 +733,31 @@ B 上的 Worker 是一条普通任务,`sessions.orca_remote_lead`(migration 01
`service.ts` 的组来源);回归见同目录 `__tests__/remoteGroup.test.ts`、`remoteHandler.test.ts`、`leaseReporter.test.ts`,
`device-link/__tests__/providerShareDispatch.test.ts`(受邀者拒绝与不泄露组摘要)。
+## 供应商组:受邀者经组所在电脑中转(P2b)
+
+产品规则见 [`provider-groups.md`](../product-rules/provider-groups.md) §4「分享的人(中转)」、§8、§9。受邀者 G 用组所在电脑 O
+分享出去的供应商,而 O 把它建成了组:O 的远程 Agent 被控端按组选一台组内电脑 M,自己作为 M 的控制端中转。G 与 O 之间的
+`maker:remote-agent:v1` 协议完全不变(中转对 G 透明);O 与 M 之间沿用同一协议,新增下面三项可选内容:
+
+- **open 载荷新增可选 `relay`**(`remote-agent/wire.ts`,`REMOTE_AGENT_RELAY_KEY_PATTERN`,16–64 位 `[A-Za-z0-9_-]`):O 为受邀者取的
+ 不透明键(按受邀者派生,不含分享与成员信息)。M 收到带 `relay` 的 open 一律按受邀者隔离运行(即使控制端是同账号的 O):
+ 受邀者目录、会话索引、续接校验与运行数按(控制端, relay)分开;同一控制端按受邀者各 16 个、合计 64 个任务。O 同时带
+ `groupAssigned`,并把 `sessionId` 换成按(受邀者, 任务 id)派生的 id、`providerId` 换成 M 上的供应商。旧 M 丢弃这个字段,
+ 所以 O 只把受邀者任务交给 caps 声明了 `guestRelay` 的同账号 M;分享来的 M 本来就把 O 当受邀者隔离,不要求这个能力。
+- **caps 新增可选 `guestRelay: true`**(`RemoteAgentCaps`):被控端能按受邀者隔离运行(供应商级授权与受邀者出站边界都已接上)。
+- **新 op `forget { relay }`**(`parseRemoteAgentRequest`):O 删除受邀者后请 M 清掉替它运行过的任务、受邀者目录与会话记录;
+ 只作用于调用方自己的 relay。旧 M 回 `REMOTE_AGENT_INVALID`(它从没接过被中转的任务)。
+- O 不信任 G 带来的 `relay` / `groupAssigned`:受邀者的这两个字段只会让任务按普通受邀者在 O 本机隔离运行,不能借此逃出
+ 受邀者隔离;O 的组路由只用 O 自己的组设置与记录。
+- 中转不解码消息与附件、不落盘(载荷原样按同一 callId 转给 M);推帧按任务串行;M 报出的路径类错误(分享暂停、远程调用
+ 关闭、连不上、太忙等)转给 G 时统一成 `REMOTE_AGENT_UNAVAILABLE`。
+- **控制端拉取器修正**(与本节同批,`remote-agent/controller/poller.ts`):一个 poll 带回数据后,若有任务没被仍在途的 poll
+ 覆盖就立刻再发一个。此前同一台电脑上已有空闲任务挂着长等待时,新打开的任务带回第一段数据后要等旧的长等待超时
+ (最长 10s)才能拿到 `started`。只影响控制端本地调度,不改 wire。
+- 不改 relay、服务器与数据库。实现:`remote-agent/host/runHost.ts`(中转与 M 端隔离)、`host/groupRelay.ts`、
+ `provider-group/guestRelay.ts`(选电脑);回归见 `remote-agent/__tests__/groupRelay.test.ts`(三端同进程)、
+ `provider-group/__tests__/guestRelay.test.ts`、`remote-agent/__tests__/poll.test.ts`。
+
## 事实来源
| 内容 | 权威来源 |
diff --git a/docs/product-rules/provider-groups.md b/docs/product-rules/provider-groups.md
index da6fdb6ad2..375eaba5cd 100644
--- a/docs/product-rules/provider-groups.md
+++ b/docs/product-rules/provider-groups.md
@@ -3,7 +3,8 @@
> 产品方案:2026-10-09 用户确认(含自动换电脑、受邀者不提醒、自定义供应商按名称匹配、不设数量上限)。
> 2026-10-10 用户确认:同账号其他电脑经组使用时**直接连到选中的组内电脑**(不经组所在电脑中转),
> 分享的人仍经组所在电脑中转;被组收进去的远程供应商与分享,在同账号其他电脑上只显示组那一项。
-> 实现进度见 §12:P1 已实现;P2 同账号直连与模型列表只显示组(P2a)已实现,分享的人经组中转(P2b)未实现;P3 未实现。
+> 实现进度见 §12:P1 已实现;P2 同账号直连与模型列表只显示组(P2a)、分享的人经组中转与启动阶段换电脑(P2b)已实现,
+> 分享的人运行中换电脑与申请弹窗新说法(P2c)未实现;P3 未实现。
> 交互设计稿见 [`docs/design-previews/provider-groups/index.html`](../design-previews/provider-groups/index.html)。
> 读取时机:新增或修改供应商组、组策略、组内电脑的添加与状态、经供应商组的任务分配或转发、
> 供应商组用量与「远程与分享」页之前。
@@ -84,7 +85,22 @@
选中分享来的电脑就用这个账号收到的那个分享(分享属于账号,§3)。少一次中转;组所在电脑关机不影响已经在跑的任务。
组所在电脑看不到这些任务的内容,任务所在的电脑把正在跑的经组任务报告给它(只用于统计负载),组内电脑出问题时把
需要冷却的电脑报告给它(§5、§6.1)。
-- **分享的人**:连不到组内其他电脑,由组所在电脑选电脑并中转(P2b)。
+- **分享的人(中转)**:连不到组内其他电脑,由组所在电脑选电脑并中转(P2b):
+ - 受邀者的**新任务**按组策略选一台:选到组所在电脑就在本机运行;选到别的电脑就由组所在电脑中转,事件、反向请求、
+ WebSocket 帧原样转发,消息与附件不解码、不落盘(§8「只在内存中转」)。受邀者带来的「已分配」「中转」字段一律
+ 当作普通受邀者任务处理,组所在电脑不让受邀者自己决定去哪台。
+ - 只选能接受受邀者的电脑:组所在电脑自己;分享来的电脑(那台本来就把组所在电脑当受邀者隔离);同账号电脑要声明
+ 能按受邀者隔离(`guestRelay`),不声明的旧版本一阵子(10 分钟)不再给它受邀者的任务,但不冷却它,组所在电脑
+ 自己的任务照常分过去。
+ - 被中转过来的任务,组内电脑一律按受邀者隔离运行(即使来自同账号的组所在电脑):受邀者目录、会话索引与运行数按
+ (组所在电脑, 受邀者)分开,受邀者在那台的身份是组所在电脑为它取的不透明键,任务 id 也按受邀者派生,两个受邀者
+ 用同一个任务 id 不会撞车。组所在电脑在同一台组内电脑上按受邀者各算 16 个任务、合计不超过 64 个。
+ - **续接**只回到当初运行这个会话的那台(组所在电脑记着「哪个会话在哪台」,那台被移出组后也回到那台),不在别处重试;
+ 受邀者不能凭 id 接回别的受邀者的会话。
+ - **启动阶段**(新任务还没开始运行)那台接不下时直接换组里下一台,受邀者无感,旧版本受邀者也享受;每次尝试的
+ WebSocket 连接编号不同,换台时关掉上一次尝试的连接。
+ - 删除受邀者(分享删除)时,组所在电脑请接过它任务的组内电脑清掉它留下的会话记录与目录(`forget`);组内电脑只清
+ 调用方自己的那个受邀者。那台当时离线则这次清不掉(已知限制:等下次组所在电脑清理时再试)。
- **防转圈**:经组分配到组内电脑的任务,在那台电脑上直接运行,不再进入那台电脑自己的供应商组。
打开任务时带一个可选标记 `groupAssigned` 说明「已由供应商组分配」;旧版本不认识这个标记,也是直接运行。
登记见 `docs/dev-rules/protocol-compatibility.md`「供应商组」。
@@ -201,6 +217,9 @@
「Agent 在 {分享者} 的电脑上运行」。不补提醒,只更新「分享给我的供应商」详情里的说明。
- 分享来的组内电脑上,组所在电脑作为受邀者照常受到受邀者隔离(供应商分享 §9);它的主人只看到组所在电脑账号的昵称与头像。
- 组所在电脑能看到经它转发的对话与文件内容,与分享者电脑一致;转发内容只在内存中转,不写入日志。
+- 组内电脑报出的、会透露它是谁或它与组所在电脑关系的错误(那台对组所在电脑的分享暂停、没开远程调用、连不上等),
+ 转给受邀者时统一成「暂时不可用」。已知差异(P2b):Agent 输出与工具路径里可能出现组内电脑上的会话目录路径(含那台的
+ 系统用户名),与受邀者直接用分享者电脑时看到分享者电脑的路径同一程度。
## 9. 安全不变量
@@ -213,7 +232,8 @@
其他电脑。组内电脑被移出组只影响之后的分配:已经在它上面的任务留在那台,成为普通的远程 Agent 任务,
不再自动换电脑;之后同一台电脑重新加入、或重建同一个组,这些任务也不会恢复自动换电脑。
5. **防转圈**(§4)。
-6. 同账号的组内电脑沿用同账号远程 Agent 的信任等级,组不改变它。
+6. 同账号的组内电脑沿用同账号远程 Agent 的信任等级,组不改变它;但组所在电脑替受邀者中转过去的任务,组内电脑一律按
+ 受邀者隔离运行,受邀者不会因为经过同账号的组所在电脑而拿到主人级权限。
7. **组内电脑的名单只给同账号电脑。** `provider-group:remote` 通道与目录里的组摘要都只给同账号电脑:受邀者与共享任务
访客调用通道一律拒绝,分享出去的目录里去掉组摘要(分享者电脑、受邀者电脑与手机各去一遍)。
@@ -270,7 +290,8 @@
|---|---|
| P1(已实现) | 供应商组设置与「远程与分享」页的组一块;组所在电脑自己的任务按组选电脑(选定后就是普通的本机或远程 Agent 任务)与自动换电脑;组内电脑状态与本次运行内的冷却;换电脑的活动记录(桌面与手机) |
| P2a(已实现) | 同账号其他电脑经组直连:问组所在电脑选电脑、直接连过去、本机自动换电脑并报告冷却;运行中任务报告给组所在电脑计入负载;防转圈标记;同账号其他电脑的模型列表与设置页只显示组、组项标出供应商组与组内电脑状态 |
-| P2b | 分享的人经组所在电脑中转;使用方隔离;同账号组内电脑接受被中转的受邀者(隔离);「需要换一台」信号与受邀者那边的自动交接;申请弹窗的新说法 |
+| P2b(已实现) | 分享的人经组所在电脑中转;使用方隔离;同账号组内电脑接受被中转的受邀者(隔离);续接回到原来那台;启动阶段换电脑;删除受邀者时通知组内电脑清理 |
+| P2c | 分享的人运行中换电脑:「需要换一台」信号与受邀者那边的自动交接、活动记录「已自动换一台电脑继续」;申请弹窗的新说法 |
| P3 | 两个维度的用量;全部失败时逐台列出原因、按全组最早恢复的一台等待;手机端显示实际运行电脑 |
## 13. 验收
@@ -300,9 +321,9 @@
| 角色 | 是旧版本时 |
|---|---|
| 组所在电脑 | 组只在新版本里存在。降级到旧版本后组不生效,这个供应商回到只在本机运行;经组分到其他电脑的任务在旧版本里不能续接,需要换模型或新开任务。同账号其他电脑问它时得到 `CHANNEL_NOT_ALLOWED`、目录里也没有组摘要,当作没有组照常直接连它;已经经它的组分到别处的任务留在原处,成为普通的远程 Agent 任务 |
-| 组内电脑 | 照常作为普通的同账号远程供应商或分享来的供应商接任务。「已由供应商组分配」标记对它是不认识的字段,解码时丢弃;它本来没有组,也不会转圈 |
+| 组内电脑 | 照常作为普通的同账号远程供应商或分享来的供应商接任务。「已由供应商组分配」标记对它是不认识的字段,解码时丢弃;它本来没有组,也不会转圈。旧版同账号组内电脑不声明 `guestRelay`,组所在电脑不给它分受邀者的任务(它不会按受邀者隔离);旧版分享来的组内电脑本来就把组所在电脑当受邀者,照常接,只是不按受邀者再细分作用域(组所在电脑自己按受邀者隔离) |
| 同账号其他电脑 | 直连由任务所在的电脑执行,旧版本不认识组:选组所在电脑的这个供应商时直接在组所在电脑上运行(没有组),模型列表里组内电脑照常单独显示、没有供应商组的标注 |
-| 分享的人 | 照常使用。打开任务阶段的换电脑由组所在电脑完成,旧版本同样享受;运行中失败时它没有声明支持「需要换一台」,组所在电脑照旧返回原来的错误(如用量上限),用户像现在一样换模型或稍后重试。(P2b) |
+| 分享的人 | 照常使用,中转对它透明(协议不变)。打开任务阶段的换电脑由组所在电脑完成,旧版本同样享受;运行中失败时它没有声明支持「需要换一台」,组所在电脑照旧返回原来的错误(如用量上限),用户像现在一样换模型或稍后重试。(运行中换电脑见 P2c) |
| 受邀者申请 | 申请弹窗由受邀者自己的 Cindy 显示,旧版本仍是原来的说法(§8 已知差异) |
- 本地数据:供应商组设置只新增存储,不改已有的供应商、远程调用与分享数据;涉及数据库时按
diff --git a/packages/device-link/src/__tests__/remoteAgent.test.ts b/packages/device-link/src/__tests__/remoteAgent.test.ts
index a6fec7b91e..38f3d5e4c3 100644
--- a/packages/device-link/src/__tests__/remoteAgent.test.ts
+++ b/packages/device-link/src/__tests__/remoteAgent.test.ts
@@ -27,6 +27,16 @@ describe('remote agent channel', () => {
expect(REMOTE_INVOKE_ALLOWLIST.has(PROVIDER_GROUP_REMOTE_CHANNEL)).toBe(true);
});
+ it('parses the provider group forget op and the guest relay capability', () => {
+ const relay = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';
+ expect(parseRemoteAgentRequest({ op: 'forget', relay, extra: 1 })).toEqual({ op: 'forget', relay });
+ expect(() => parseRemoteAgentRequest({ op: 'forget', relay: 'short' })).toThrow('REMOTE_AGENT_INVALID');
+ expect(() => parseRemoteAgentRequest({ op: 'forget' })).toThrow('REMOTE_AGENT_INVALID');
+ const caps = { version: 1, agents: [], maxRuns: 16, uploadChunkBytes: 1024, maxPayloadBytes: 2048 };
+ expect(parseRemoteAgentCaps({ ...caps, guestRelay: true }).guestRelay).toBe(true);
+ expect(parseRemoteAgentCaps({ ...caps, guestRelay: 'yes' })).not.toHaveProperty('guestRelay');
+ });
+
it('parses every op and drops unknown fields', () => {
expect(parseRemoteAgentRequest({ op: 'caps', x: 1 })).toEqual({ op: 'caps' });
expect(parseRemoteAgentRequest({ op: 'open', runId, agentKind: 'pi', payload: { json: { a: 1 } }, extra: 1 }))
diff --git a/packages/device-link/src/remoteAgent.ts b/packages/device-link/src/remoteAgent.ts
index 23bb847f2c..2129671829 100644
--- a/packages/device-link/src/remoteAgent.ts
+++ b/packages/device-link/src/remoteAgent.ts
@@ -154,7 +154,16 @@ export type RemoteAgentRequest =
| { op: 'poll'; runs: Array<{ runId: string; cursor: number }>; waitMs?: number }
| { op: 'reply'; runId: string; requestId: string; payload: RemoteAgentPayload }
| { op: 'push'; runId: string; seq: number; frames: RemoteAgentPushFrame[] }
- | { op: 'close'; runId: string; mode: 'close' | 'detach'; reason: RemoteAgentTeardownReason };
+ | { op: 'close'; runId: string; mode: 'close' | 'detach'; reason: RemoteAgentTeardownReason }
+ /**
+ * 供应商组(组所在电脑 → 组内电脑):组所在电脑删掉某个受邀者后,请组内电脑清掉替这个受邀者
+ * 运行过的任务留下的会话记录与目录。relay 是组所在电脑为受邀者取的不透明键(打开任务时随载荷带过来),
+ * 只作用于调用方自己的 relay。旧版组内电脑回 REMOTE_AGENT_INVALID(它从没接过被中转的任务)。
+ */
+ | { op: 'forget'; relay: string };
+
+/** 供应商组为受邀者取的不透明键(组所在电脑按受邀者派生,不含身份信息)。 */
+export const REMOTE_AGENT_RELAY_KEY_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
/** 与 maker-core AgentSessionTeardownReason 同值。 */
export const REMOTE_AGENT_TEARDOWN_REASONS = ['navigation', 'account-boundary', 'app-quit'] as const;
@@ -168,6 +177,11 @@ export interface RemoteAgentCaps {
maxPayloadBytes: number;
/** 是否支持 opaque 虚拟工作区;不支持时控制端必须拒绝启动以免泄露真实路径。 */
virtualWorkspace?: boolean;
+ /**
+ * 供应商组:能接受同账号组所在电脑中转过来的受邀者任务(打开时带 relay 键就按受邀者隔离运行)。
+ * 不声明的电脑,组所在电脑不给它分受邀者的任务(否则受邀者会拿到主人级权限)。
+ */
+ guestRelay?: boolean;
}
export interface RemoteAgentReadResult {
@@ -334,6 +348,9 @@ export function parseRemoteAgentRequest(value: unknown): RemoteAgentRequest {
mode: oneOf(v.mode, ['close', 'detach'] as const),
reason: oneOf(v.reason, REMOTE_AGENT_TEARDOWN_REASONS),
};
+ case 'forget':
+ if (typeof v.relay !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(v.relay)) invalid();
+ return { op: 'forget', relay: v.relay };
default:
invalid();
}
@@ -367,6 +384,7 @@ export function parseRemoteAgentCaps(value: unknown): RemoteAgentCaps {
uploadChunkBytes: count(v.uploadChunkBytes, REMOTE_AGENT_UPLOAD_CHUNK_BYTES),
maxPayloadBytes: count(v.maxPayloadBytes, Number.MAX_SAFE_INTEGER),
...(v.virtualWorkspace === true ? { virtualWorkspace: true } : {}),
+ ...(v.guestRelay === true ? { guestRelay: true } : {}),
};
if (caps.version < 1 || caps.maxRuns < 1 || caps.uploadChunkBytes < 1) invalid();
return caps;