Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 供应商组的 Renderer ↔ Main 契约(只在本机进程之间)。
*
* 一台电脑上的某个供应商可以建一个供应商组,把这台电脑已经能用的同一个供应商(本机、同账号
* 电脑上已开「允许被远程调用」的、别人分享给这个账号的)合成一组;之后这个供应商的使用按组策略
* 选一台组内电脑运行 Agent。产品规则见 docs/product-rules/provider-groups.md。
*/
import { isProviderShareAgentDeviceId, PROVIDER_SHARE_AGENT_DEVICE_PREFIX } from './providerShare.js';
import type { ProviderManagementRequest, ProviderManagementResult } from './providerManagement';
export const PROVIDER_GROUP_IPC = {
/** Renderer → Main:全部操作走同一个命令通道。 */
COMMAND: 'provider-group:command',
/** 某个供应商的组设置变化。payload: { providerId: string } */
CHANGED: 'provider-group:changed',
} as const;
export type ProviderGroupStrategy = 'least' | 'round' | 'order' | 'weight' | 'usage';
export const PROVIDER_GROUP_STRATEGIES: readonly ProviderGroupStrategy[] = ['least', 'round', 'order', 'weight', 'usage'];
export type ProviderGroupMemberKind = 'local' | 'device' | 'share';
/** 每台组内电脑默认同时接几个任务。 */
export const PROVIDER_GROUP_DEFAULT_LIMIT = 4;
/** 远程 Agent 对每个控制端最多 16 个任务,组内电脑的并发上限不超过它。 */
export const PROVIDER_GROUP_MAX_LIMIT = 16;
export const PROVIDER_GROUP_DEFAULT_WEIGHT = 1;
export const PROVIDER_GROUP_MAX_WEIGHT = 100;
/**
* 组内电脑数量不设产品上限;这里只是防止损坏的设置文件无限膨胀的存储边界,远高于实际用量。
*/
export const PROVIDER_GROUP_STORAGE_MEMBER_CAP = 512;
export const PROVIDER_GROUP_LOCAL_MEMBER_KEY = 'local';
export interface ProviderGroupMember {
/** 稳定键:`local` / `device:<deviceId>:<providerId>` / `share:<shareId>:<providerId>`。 */
key: string;
kind: ProviderGroupMemberKind;
/** 运行 Agent 的电脑:null = 本机;同账号电脑的设备 id;分享来的为 `share:<shareId>`。 */
agentDeviceId: string | null;
/** 那台电脑上这个供应商的 id(各电脑上可能不同,例如订阅账号带随机后缀)。 */
providerId: string;
/** 加入时的显示名快照,那台电脑离线时展示。 */
label?: string;
/** 加入时的供应商显示名快照;用于同一台电脑上的多个供应商账号区分。 */
providerName?: string;
/**
* 分享来的电脑:分享者那台电脑的设备 id(本账号收到的分享里本来就有)。只用来把同一台电脑上的几个分享
* 按一台电脑展示与计数,不显示、不用于连接;不会发给受邀者。旧组没有时由组所在电脑对账补上(removedShares.ts)。
*/
hostDeviceId?: string;
/** 并发上限:只统计经本组分到这台的任务。 */
limit: number;
weight: number;
/** 暂停组内新任务分配;本机成员只暂停接收外部新任务,不影响本机自用或已有任务。 */
paused: boolean;
}
export interface ProviderGroupConfig {
/** Subscription-only speed policy. Absent preserves the existing allowed default. */
allowFast?: boolean;
strategy: ProviderGroupStrategy;
/** 组内电脑失败时自动换一台继续,默认开启。 */
autoSwitch: boolean;
members: ProviderGroupMember[];
}
export type ProviderGroupMemberState =
/** 可以接新任务。 */
| 'available'
/** 已达到并发上限。 */
| 'full'
/** 暂停分配。 */
| 'paused'
/** 撞到用量上限后冷却中。 */
| 'cooling'
/** 连不上(离线、未开远程控制、分享者电脑不在线)。 */
| 'offline'
/** 连得上,但这个供应商现在不能用。 */
| 'unavailable';
export type ProviderGroupUnavailableReason =
/** 那台没对这个供应商打开「允许被远程调用」,或目录里已没有这个供应商。 */
| 'provider-off'
/** 供应商未连接或已停用。 */
| 'disconnected'
| 'share-paused'
| 'share-removed';
export interface ProviderGroupMemberStatus {
key: string;
kind: ProviderGroupMemberKind;
/** 设备名(本机为本机设备名)。 */
label: string;
/** 那台电脑上这个供应商的显示名;旧组或旧端未提供时省略。 */
providerName?: string;
/** 分享来的电脑:分享者昵称。 */
ownerName?: string;
/** Cindy 应用版本;缺失表示旧端或分享来源未提供,不是 remote-agent 协议版本。 */
appVersion?: string;
/** 仅描述接收分享任务的能力,不改变主人自己的可用状态。 */
guestSupport?: ProviderGroupGuestSupport;
state: ProviderGroupMemberState;
reason?: ProviderGroupUnavailableReason;
/** 经本组分到这台、正在运行的任务数。 */
running: number;
limit: number;
weight: number;
paused: boolean;
/** 冷却到何时(unix ms)。 */
coolingUntil?: number;
/**
* 选电脑时排序用的那个配额窗口(provider-groups.md §5):本机与同账号电脑的订阅才有,读不到时省略。
* 发给同账号电脑,用来提议任务进行中换号(§6.2),界面不显示;不进受邀者的匿名状态。
*/
quota?: ProviderGroupMemberQuota;
/**
* 5 小时配额快满、离重置还早(provider-groups.md §5「配额先比」第 0 条):任务进行中不提议换到这台。只在为真时出现,
* 规则同 `quota`。
*/
fiveHourTight?: true;
/**
* 另一台电脑上的组:组所在电脑那边看它能用,这台电脑却连不上(provider-groups.md §10)。只由这台电脑的主进程
* 按自己的连接情况补上,不来自组所在电脑的回包。
*/
unreachableHere?: boolean;
/**
* 分享来的电脑:这台的主人对本机分享出去的人逐人同意的结果(provider-sharing.md §4.3)。只在本机自己的组里、
* 组所在的供应商分享给了别人时有;不经设备互联发给其他电脑。
*/
reshare?: ProviderGroupReshareSummary;
}
/** 一个配额窗口此刻的用量:已用多少、何时重置、窗口多长,够算出这个账号的额度有多急着用。 */
export interface ProviderGroupMemberQuota {
usedPercent: number;
/** 重置时刻(unix ms);null = 这个窗口还没开始计时。 */
resetAtMs: number | null;
/** 窗口长度(ms),周配额是 7 天。 */
windowMs: number;
}
/** 最长按 31 天的窗口接收,超出或格式不对就当没有。 */
const MAX_QUOTA_WINDOW_MS = 31 * 86_400_000;
export function readProviderGroupMemberQuota(value: unknown): ProviderGroupMemberQuota | undefined {
if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
const { usedPercent, resetAtMs, windowMs } = value as Record<string, unknown>;
if (typeof usedPercent !== 'number' || !Number.isFinite(usedPercent)) return undefined;
if (typeof windowMs !== 'number' || !Number.isFinite(windowMs) || windowMs <= 0 || windowMs > MAX_QUOTA_WINDOW_MS) return undefined;
if (resetAtMs !== null && (typeof resetAtMs !== 'number' || !Number.isFinite(resetAtMs) || resetAtMs <= 0)) return undefined;
return { usedPercent: Math.min(100, Math.max(0, usedPercent)), resetAtMs, windowMs };
}
/**
* 任务进行中换号的提议(provider-groups.md §6.2「任务进行中换号」):用户自己发下一条消息前问任务所在的电脑。
* `ask` = 弹窗问;`auto` = 同账号先尝试原生接续,或任务已有自动换号偏好。原生失败由宿主单独确认摘要回退。
* `label` 是要换去的那台(带账号名)。旧客户端已支持 auto,无需新增协议字段。
*/
export type ProviderGroupRebalanceSuggestion =
| { kind: 'ask' | 'auto'; memberKey: string; label: string; quota: ProviderGroupMemberQuota }
| null;
const REBALANCE_MEMBER_KEY_PATTERN = /^[A-Za-z0-9_.:-]{1,300}$/;
/** 电脑名与账号名各最多 128 个 UTF-16 单元,组合时另加分隔符。 */
export const PROVIDER_GROUP_REBALANCE_LABEL_MAX_LENGTH = 128 * 2 + 3;
/** 客户端读任务所在电脑回的提议;旧端不认识这个动作、格式不对都按没有提议处理(照常发送)。 */
export function parseProviderGroupRebalanceSuggestion(raw: unknown): ProviderGroupRebalanceSuggestion {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
const value = raw as Record<string, unknown>;
if (value.kind !== 'ask' && value.kind !== 'auto') return null;
if (typeof value.memberKey !== 'string' || !REBALANCE_MEMBER_KEY_PATTERN.test(value.memberKey)) return null;
const label = normalizeLabel(value.label, PROVIDER_GROUP_REBALANCE_LABEL_MAX_LENGTH);
const quota = readProviderGroupMemberQuota(value.quota);
return label && quota ? { kind: value.kind, memberKey: value.memberKey, label, quota } : null;
}
/** 本机分享出去的一个人:分享来的那台电脑的主人是否同意他经组使用那台。 */
export interface ProviderGroupReshareGuest {
memberId: string;
displayName: string;
avatarUrl: string | null;
/** unknown = 还没问到(那台离线或刚加入)。 */
state: 'approved' | 'pending' | 'rejected' | 'unknown';
}
export interface ProviderGroupReshareSummary {
/** needs-update = 那台的 Cindy 太旧,给不出同意;unknown = 还没问到。 */
support: 'supported' | 'needs-update' | 'unknown';
guests: ProviderGroupReshareGuest[];
}
export interface ProviderGroupView {
/** Some executors have not confirmed this group's subscription speed policy yet. */
fastPolicyPending?: boolean;
providerId: string;
/** null = 还没有组。 */
config: ProviderGroupConfig | null;
members: ProviderGroupMemberStatus[];
/** 发送前按指定模型重新计算状态时由组所在电脑回显。 */
model?: string;
}
export type ProviderGroupGuestSupport = 'supported' | 'needs-update' | 'unknown';
/** 设备目录中的应用版本只用于展示,拒绝异常长字符串和非版本文本。 */
export function readProviderGroupAppVersion(value: unknown): string | undefined {
return typeof value === 'string' && value.length <= 64 && /^[0-9]+[.][0-9]+[.][0-9]+(?:[-+][0-9A-Za-z.+-]+)?$/.test(value)
? value : undefined;
}
export type ProviderGroupCandidateBlock =
/** 已在组里。 */
| 'member'
| 'offline'
/** 不是同一个供应商。 */
| 'mismatch';
export interface ProviderGroupCandidate {
key: string;
kind: 'device' | 'share';
agentDeviceId: string;
providerId: string;
/** 设备名。 */
label: string;
/** 那台电脑上这个供应商的显示名。 */
providerName: string;
ownerName?: string;
/** 分享来的:分享者那台电脑的设备 id(同一台电脑的几个分享收在一起)。 */
hostDeviceId?: string;
blocked?: ProviderGroupCandidateBlock;
}
export type ProviderGroupLocalCommand =
| { action: 'get'; providerId: string }
| { action: 'candidates'; providerId: string }
| { action: 'save'; providerId: string; config: ProviderGroupConfig }
| { action: 'delete'; providerId: string }
/** 设置页按编辑时的完整配置保存;null 表示当时尚未建组。独立动作让旧端明确拒绝。 */
| { action: 'save-if-current'; providerId: string; config: ProviderGroupConfig; expectedConfig: ProviderGroupConfig | null }
| { action: 'delete-if-current'; providerId: string; expectedConfig: ProviderGroupConfig | null }
/** 同账号另一台电脑上这个供应商的组与组内电脑状态(只读)。 */
| { action: 'remote-view'; providerId: string; deviceId: string }
/** 本机全部组的设置(不读远端)。 */
| { action: 'list' }
/** 这个任务此刻归哪个组(模型列表把它显示在组那一项下)。 */
| { action: 'session-group'; sessionId: string }
/** 用户发下一条消息前:要不要提议换号(provider-groups.md §6.2「任务进行中换号」)。 */
| { action: 'rebalance-suggestion'; sessionId: string }
/** 用户确认换号:这个任务的下一条消息先换到 `memberKey`;`remember` = 这个任务以后自动换。 */
| { action: 'rebalance-decision'; sessionId: string; memberKey: string; remember: boolean; clientId?: string };
export type ProviderGroupCommand = ProviderGroupLocalCommand
| { action: 'remote-manage'; deviceId: string; request: ProviderManagementRequest };
/**
* 任务此刻归的组:`groupDeviceId` 为组所在电脑,null = 这台电脑自己建的组;`providerId` 是组那一项在组所在电脑上的
* 供应商 id。没归组(或位置与绑定对不上)为 null。
*/
export type ProviderGroupSessionGroup = { groupDeviceId: string | null; providerId: string } | null;
export type ProviderGroupCommandResult<C extends ProviderGroupCommand> =
C extends { action: 'remote-manage'; request: infer R extends ProviderManagementRequest } ? ProviderManagementResult<R>
: C extends { action: 'list' } ? Record<string, ProviderGroupConfig>
: C extends { action: 'get' } ? ProviderGroupView
: C extends { action: 'candidates' } ? ProviderGroupCandidate[]
: C extends { action: 'save' | 'save-if-current' } ? ProviderGroupView
: C extends { action: 'delete' | 'delete-if-current' } ? ProviderGroupView
: C extends { action: 'remote-view' } ? ProviderGroupView
: C extends { action: 'session-group' } ? ProviderGroupSessionGroup
: C extends { action: 'rebalance-suggestion' } ? ProviderGroupRebalanceSuggestion
: C extends { action: 'rebalance-decision' } ? { ok: boolean }
: never;
const PROVIDER_ID_PATTERN = /^[a-zA-Z0-9._-]{1,128}$/;
const DEVICE_ID_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
const SHARE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
export function isProviderGroupProviderId(value: unknown): value is string {
return typeof value === 'string' && PROVIDER_ID_PATTERN.test(value);
}
/** 组内电脑的稳定键:同一台电脑上的同一个供应商只能在组里出现一次。 */
export function providerGroupMemberKey(agentDeviceId: string | null, providerId: string): string {
if (agentDeviceId === null) return PROVIDER_GROUP_LOCAL_MEMBER_KEY;
if (isProviderShareAgentDeviceId(agentDeviceId)) {
return `share:${agentDeviceId.slice(PROVIDER_SHARE_AGENT_DEVICE_PREFIX.length)}:${providerId}`;
}
return `device:${agentDeviceId}:${providerId}`;
}
function isAgentDeviceIdFor(kind: ProviderGroupMemberKind, value: unknown): boolean {
if (kind === 'local') return value === null;
if (typeof value !== 'string') return false;
if (kind === 'share') {
return isProviderShareAgentDeviceId(value)
&& SHARE_ID_PATTERN.test(value.slice(PROVIDER_SHARE_AGENT_DEVICE_PREFIX.length));
}
return !isProviderShareAgentDeviceId(value) && DEVICE_ID_PATTERN.test(value);
}
function clampInt(value: unknown, min: number, max: number, fallback: number): number {
if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
return Math.min(max, Math.max(min, Math.round(value)));
}
function normalizeLabel(value: unknown, maxLength = 128): string | undefined {
if (typeof value !== 'string') return undefined;
const trimmed = value.trim();
// eslint-disable-next-line no-control-regex -- 控制字符是显式拒绝目标
if (!trimmed || trimmed.length > maxLength || /[\u0000-\u001f\u007f]/.test(trimmed)) return undefined;
return trimmed;
}
function normalizeMember(raw: unknown, groupProviderId: string): ProviderGroupMember | null {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
const value = raw as Record<string, unknown>;
const kind = value.kind;
if (kind !== 'local' && kind !== 'device' && kind !== 'share') return null;
const agentDeviceId = kind === 'local' ? null : value.agentDeviceId;
if (!isAgentDeviceIdFor(kind, agentDeviceId)) return null;
// 本机组员就是组所属的这个供应商本身。
const providerId = kind === 'local' ? groupProviderId : value.providerId;
if (!isProviderGroupProviderId(providerId)) return null;
const label = normalizeLabel(value.label);
const providerName = normalizeLabel(value.providerName);
const hostDeviceId = kind === 'share' ? normalizeShareHostDeviceId(value.hostDeviceId) : undefined;
return {
key: providerGroupMemberKey(agentDeviceId as string | null, providerId),
kind,
agentDeviceId: agentDeviceId as string | null,
providerId,
...(label ? { label } : {}),
...(providerName ? { providerName } : {}),
...(hostDeviceId ? { hostDeviceId } : {}),
limit: clampInt(value.limit, 1, PROVIDER_GROUP_MAX_LIMIT, PROVIDER_GROUP_DEFAULT_LIMIT),
weight: clampInt(value.weight, 1, PROVIDER_GROUP_MAX_WEIGHT, PROVIDER_GROUP_DEFAULT_WEIGHT),
paused: value.paused === true,
};
}
function normalizeShareHostDeviceId(value: unknown): string | undefined {
// Provider-share host IDs use the shared-task device domain: any non-empty
// string up to 128 UTF-16 code units. They are opaque and never used as a
// connection address here, so do not apply the narrower local-device regex.
return typeof value === 'string' && value.length > 0 && value.length <= 128
? value
: undefined;
}
export type ProviderGroupPhysicalMember = Pick<ProviderGroupMember, 'kind' | 'agentDeviceId' | 'hostDeviceId'>;
/**
* 供应商组展示与计数用的物理电脑键;账号仍由 member.key 独立区分。分享来的按分享者那台电脑:同一个人从同一台电脑
* 分享的几个账号算一台;还不知道那台电脑时(旧组尚未对账)按分享各算一台。分享者的电脑一定属于别的账号,不会与自己的电脑重合。
*/
export function providerGroupPhysicalDeviceKey(member: ProviderGroupPhysicalMember): string {
if (member.kind === 'local') return PROVIDER_GROUP_LOCAL_MEMBER_KEY;
if (member.kind === 'share' && member.hostDeviceId) return `share-host:${member.hostDeviceId}`;
return `${member.kind}:${member.agentDeviceId ?? ''}`;
}
/** 组里实际的物理电脑数。同一台电脑上的多个供应商账号(含同一台分享来的几个)只算一台。 */
export function providerGroupDeviceCount(members: readonly ProviderGroupPhysicalMember[]): number {
return new Set(members.map(providerGroupPhysicalDeviceKey)).size;
}
/**
* 校正一份组设置(存储读取与 IPC 写入共用)。没有组内电脑 = 没有组,返回 null:
* 组里至少保留一台,移除最后一台即删除组。
*/
export function normalizeProviderGroupConfig(raw: unknown, groupProviderId: string): ProviderGroupConfig | null {
if (!isProviderGroupProviderId(groupProviderId)) return null;
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
const value = raw as Record<string, unknown>;
const strategy = PROVIDER_GROUP_STRATEGIES.includes(value.strategy as ProviderGroupStrategy)
? value.strategy as ProviderGroupStrategy
: 'least';
const members: ProviderGroupMember[] = [];
const seen = new Set<string>();
for (const entry of Array.isArray(value.members) ? value.members : []) {
if (members.length >= PROVIDER_GROUP_STORAGE_MEMBER_CAP) break;
const member = normalizeMember(entry, groupProviderId);
if (!member || seen.has(member.key)) continue;
seen.add(member.key);
members.push(member);
}
if (members.length === 0) return null;
return { strategy, autoSwitch: value.autoSwitch !== false, members,
...(typeof value.allowFast === 'boolean' ? { allowFast: value.allowFast } : {}) };
}
// ─── 同账号电脑之间(`maker:provider:list` 的 `group` 字段与 `provider-group:remote` 通道) ─────
/**
* 组所在电脑的目录里随组所属供应商带出的组摘要:只给同账号电脑,受邀者与共享任务访客看不到。
* 组员的坐标是组所在电脑视角(`local` = 组所在电脑自己)。并发上限与权重只在组所在电脑上生效,不外发。
*/
export interface ProviderGroupWireSummary {
allowFast?: boolean;
strategy: ProviderGroupStrategy;
autoSwitch: boolean;
members: Array<Pick<ProviderGroupMember,
'key' | 'kind' | 'agentDeviceId' | 'providerId' | 'label' | 'providerName' | 'hostDeviceId' | 'paused'>>;
}
export function providerGroupSummaryForWire(config: ProviderGroupConfig): ProviderGroupWireSummary {
return {
...(config.allowFast !== undefined ? { allowFast: config.allowFast } : {}),
strategy: config.strategy,
autoSwitch: config.autoSwitch,
members: config.members.map((m) => ({
key: m.key,
kind: m.kind,
agentDeviceId: m.agentDeviceId,
providerId: m.providerId,
// 分享来的电脑不带名字:旧版本存的快照是分享者的电脑名(provider-sharing.md §6),界面按分享者昵称显示。
...(m.label && m.kind !== 'share' ? { label: m.label } : {}),
...(m.providerName ? { providerName: m.providerName } : {}),
// 同账号电脑据此把同一台分享来的几个账号算一台;组摘要不发给受邀者。
...(m.hostDeviceId ? { hostDeviceId: m.hostDeviceId } : {}),
paused: m.paused,
})),
};
}
/** 读另一台电脑目录里的组摘要;格式不对返回 null(当作没有组)。 */
export function readProviderGroupSummary(raw: unknown, groupProviderId: string): ProviderGroupConfig | null {
return normalizeProviderGroupConfig(raw, groupProviderId);
}
/** 换电脑的原因里,会让组所在电脑冷却那台的几种(连不上只由发现它的电脑自己避开,不替全组判断)。 */
export type ProviderGroupRemoteCoolCause = 'usage-limit' | 'auth' | 'overload';
const REMOTE_COOL_CAUSES: readonly ProviderGroupRemoteCoolCause[] = ['usage-limit', 'auth', 'overload'];
export interface ProviderGroupRemoteLease {
sessionId: string;
providerId: string;
memberKey: string;
}
/**
* 同账号电脑报告的一行用量:它经组所在电脑的组、在组里别的电脑上运行的部分(provider-groups.md §7),
* 供应商与组内电脑都是组所在电脑的坐标,按天、Agent、模型聚合。
*/
export interface ProviderGroupRemoteUsageRow {
day: string;
providerId: string;
memberKey: string;
kind: string;
model: string;
turns: number;
inputTokens: number;
outputTokens: number;
cacheReadTokens: number;
cacheCreateTokens: number;
sdkCostUsd: number;
/** 这一行最近一次记账的时间(unix ms)。 */
lastAt: number;
}
/** 单次请求的行数上限;完整报告超过此值时用 usage-part 分批收齐后再替换。 */
export const PROVIDER_GROUP_REMOTE_MAX_USAGE_ROWS = 3_000;
/** 完整报告的上限,与按使用方账本的保留行数一致;不提高单帧上限。 */
export const PROVIDER_GROUP_REMOTE_MAX_USAGE_REPORT_ROWS = 20_000;
export interface ProviderGroupUsagePartAck {
seq: number;
received: number;
committed: boolean;
}
export type ProviderGroupRemoteRequest =
/** 新任务该用组里哪台;选中即给那台记一个短暂的占用,同时开的几个任务不会全落到同一台。 */
| { action: 'pick'; sessionId: string; providerId: string; agentKind: 'claude-code' | 'codex' | 'pi'; model: string; exclude: string[]; quotaRebalance?: string }
/** 那台电脑出了问题(用量上限、登录失效、服务繁忙):组所在电脑冷却它,不再分新任务。 */
| { action: 'cool' | 'cool-model'; providerId: string; memberKey: string; cause: ProviderGroupRemoteCoolCause; resetAt?: number; model?: string }
/** 这台电脑经组运行、正在跑的任务(整体替换上一份;seq 只增,乱序到达的旧份丢弃)。 */
| { action: 'leases'; seq: number; entries: ProviderGroupRemoteLease[] }
/** 组内电脑的状态(发送前检查、设置页展示)。 */
| { action: 'view'; providerId: string; model?: string; agentKind?: 'claude-code' | 'codex' | 'pi'; includeGuestSupport?: true }
/**
* 这台电脑经组、在组里别的电脑上运行的用量(组所在电脑经手不到):整体替换这台从 sinceDay 起(含;null = 全部)
* 报过的行。seq 只增,乱序到达的旧份丢弃。
*/
| { action: 'usage'; seq: number; sinceDay: string | null; rows: ProviderGroupRemoteUsageRow[] }
/** 新动作防止旧端忽略分批字段后把半份报告当整份替换。offset 从 0 开始,收齐 total 才提交。 */
| { action: 'usage-part'; seq: number; sinceDay: string | null; offset: number; total: number; rows: ProviderGroupRemoteUsageRow[] }
/**
* 只读:这台电脑上的某个任务此刻归哪个组(手机与远程控制的模型列表用,provider-groups.md §10)。
* 发给任务所在的电脑,不是组所在电脑。
*/
| { action: 'session-group'; sessionId: string }
/** 发给任务所在的电脑(手机、远程控制):同本机命令的 `rebalance-suggestion` / `rebalance-decision`。 */
| { action: 'rebalance-suggestion'; sessionId: string }
| { action: 'rebalance-decision'; sessionId: string; memberKey: string; remember: boolean; clientId?: string };
/** `session-group` 的回包:坐标是任务所在电脑视角(`groupDeviceId` 为 null = 那台自己建的组)。 */
export interface ProviderGroupRemoteSessionGroup {
group: ProviderGroupSessionGroup;
}
/** Only verified subscription exhaustion; never inferred from a generic cooldown. */
export interface ProviderGroupUsageLimit {
/** Earliest reset of an otherwise eligible member; null when no reset is known. */
resetAtMs: number | null;
}
export type ProviderGroupRemotePick =
/** 那个供应商现在没有组(组被删了或旧版本):照常直接在组所在电脑上运行。 */
| { kind: 'none' }
| { kind: 'member'; member: Pick<ProviderGroupMember, 'key' | 'kind' | 'agentDeviceId' | 'providerId'>; label: string }
| { kind: 'unavailable'; usageLimit?: ProviderGroupUsageLimit };
/** 一次最多报告的运行中任务数(每台电脑的任务上限远低于此)。 */
export const PROVIDER_GROUP_REMOTE_MAX_LEASES = 512;
const REMOTE_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
const REMOTE_MEMBER_KEY = /^[A-Za-z0-9_.:-]{1,300}$/;
const REMOTE_AGENT_KINDS = new Set(['claude-code', 'codex', 'pi']);
function invalidRemote(message: string): never {
throw new Error(`[INVALID_PARAMS] ${message}`);
}
function remoteRecord(raw: unknown): Record<string, unknown> {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) invalidRemote('provider group request must be an object');
return raw as Record<string, unknown>;
}
function remoteProviderId(value: unknown): string {
if (!isProviderGroupProviderId(value)) invalidRemote('invalid provider id');
return value;
}
function remoteMemberKey(value: unknown): string {
if (typeof value !== 'string' || !REMOTE_MEMBER_KEY.test(value)) invalidRemote('invalid member key');
return value;
}
function remoteSessionId(value: unknown): string {
if (typeof value !== 'string' || !REMOTE_SESSION_ID.test(value)) invalidRemote('invalid session id');
return value;
}
const REMOTE_DAY = /^\d{4}-\d{2}-\d{2}$/;
const USAGE_NUMBER_FIELDS = ['turns', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreateTokens', 'sdkCostUsd', 'lastAt'] as const;
/** 用量行按数组发送(省掉每行重复的字段名):[day, providerId, memberKey, kind, model, ...USAGE_NUMBER_FIELDS]。 */
export function providerGroupUsageRowsForWire(rows: readonly ProviderGroupRemoteUsageRow[]): unknown[][] {
return rows.map((row) => [
row.day, row.providerId, row.memberKey, row.kind, row.model, ...USAGE_NUMBER_FIELDS.map((field) => row[field]),
]);
}
function remoteUsageRow(raw: unknown): ProviderGroupRemoteUsageRow {
if (!Array.isArray(raw) || raw.length !== 5 + USAGE_NUMBER_FIELDS.length) invalidRemote('invalid usage row');
const [day, providerId, memberKey, kind, model] = raw;
if (typeof day !== 'string' || !REMOTE_DAY.test(day)) invalidRemote('invalid usage day');
if (typeof kind !== 'string' || !REMOTE_AGENT_KINDS.has(kind)) invalidRemote('invalid agent');
if (typeof model !== 'string' || model.length > 512) invalidRemote('invalid model');
const row = { day, providerId: remoteProviderId(providerId), memberKey: remoteMemberKey(memberKey), kind, model } as ProviderGroupRemoteUsageRow;
USAGE_NUMBER_FIELDS.forEach((field, index) => {
const value = raw[5 + index];
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) invalidRemote('invalid usage number');
row[field] = value;
});
return row;
}
/** 组所在电脑解析同账号电脑发来的请求;不合法抛 `[INVALID_PARAMS]`。 */
export function parseProviderGroupRemoteRequest(raw: unknown): ProviderGroupRemoteRequest {
const value = remoteRecord(raw);
switch (value.action) {
case 'pick': {
const agentKind = value.agentKind;
if (typeof agentKind !== 'string' || !REMOTE_AGENT_KINDS.has(agentKind)) invalidRemote('invalid agent');
if (typeof value.model !== 'string' || !value.model || value.model.length > 512) invalidRemote('invalid model');
const exclude = value.exclude === undefined ? [] : value.exclude;
if (!Array.isArray(exclude) || exclude.length > PROVIDER_GROUP_STORAGE_MEMBER_CAP) invalidRemote('invalid exclude');
return {
action: 'pick',
sessionId: remoteSessionId(value.sessionId),
providerId: remoteProviderId(value.providerId),
agentKind: agentKind as 'claude-code' | 'codex' | 'pi',
model: value.model,
exclude: exclude.map(remoteMemberKey),
...(value.quotaRebalance !== undefined ? { quotaRebalance: remoteMemberKey(value.quotaRebalance) } : {}),
};
}
case 'cool':
case 'cool-model': {
if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim() || value.model.length > 512)) invalidRemote('invalid model');
if (value.action === 'cool-model' && (typeof value.model !== 'string' || value.cause !== 'usage-limit')) invalidRemote('invalid model cooldown');
const cause = value.cause;
if (!REMOTE_COOL_CAUSES.includes(cause as ProviderGroupRemoteCoolCause)) invalidRemote('invalid cause');
const resetAt = typeof value.resetAt === 'number' && Number.isFinite(value.resetAt) && value.resetAt > 0
? value.resetAt
: undefined;
return {
action: value.action,
providerId: remoteProviderId(value.providerId),
memberKey: remoteMemberKey(value.memberKey),
cause: cause as ProviderGroupRemoteCoolCause,
...(typeof value.model === 'string' ? { model: value.model } : {}),
...(resetAt !== undefined ? { resetAt } : {}),
};
}
case 'leases': {
if (!Number.isSafeInteger(value.seq) || (value.seq as number) < 0) invalidRemote('invalid seq');
if (!Array.isArray(value.entries) || value.entries.length > PROVIDER_GROUP_REMOTE_MAX_LEASES) invalidRemote('invalid leases');
return {
action: 'leases',
seq: value.seq as number,
entries: value.entries.map((entry) => {
const lease = remoteRecord(entry);
return {
sessionId: remoteSessionId(lease.sessionId),
providerId: remoteProviderId(lease.providerId),
memberKey: remoteMemberKey(lease.memberKey),
};
}),
};
}
case 'view': {
if (value.agentKind !== undefined && (typeof value.agentKind !== 'string' || !REMOTE_AGENT_KINDS.has(value.agentKind))) {
invalidRemote('invalid agent');
}
if (value.model !== undefined && (typeof value.model !== 'string' || !value.model || value.model.length > 512)) {
invalidRemote('invalid model');
}
return {
action: 'view',
providerId: remoteProviderId(value.providerId),
...(value.model !== undefined ? { model: value.model } : {}),
...(value.agentKind !== undefined ? { agentKind: value.agentKind as 'claude-code' | 'codex' | 'pi' } : {}),
...(value.includeGuestSupport === true ? { includeGuestSupport: true } : {}),
};
}
case 'usage':
case 'usage-part': {
if (!Number.isSafeInteger(value.seq) || (value.seq as number) < 0) invalidRemote('invalid seq');
const sinceDay = value.sinceDay ?? null;
if (sinceDay !== null && (typeof sinceDay !== 'string' || !REMOTE_DAY.test(sinceDay))) invalidRemote('invalid since day');
if (!Array.isArray(value.rows) || value.rows.length > PROVIDER_GROUP_REMOTE_MAX_USAGE_ROWS) invalidRemote('invalid usage rows');
const report = { seq: value.seq as number, sinceDay: sinceDay as string | null, rows: value.rows.map(remoteUsageRow) };
if (value.action === 'usage') return { action: 'usage', ...report };
if (!Number.isSafeInteger(value.total) || (value.total as number) < 1
|| (value.total as number) > PROVIDER_GROUP_REMOTE_MAX_USAGE_REPORT_ROWS) invalidRemote('invalid usage total');
if (!Number.isSafeInteger(value.offset) || (value.offset as number) < 0
|| report.rows.length === 0 || (value.offset as number) + report.rows.length > (value.total as number)) invalidRemote('invalid usage offset');
return { action: 'usage-part', ...report, offset: value.offset as number, total: value.total as number };
}
case 'session-group':
return { action: 'session-group', sessionId: remoteSessionId(value.sessionId) };
case 'rebalance-suggestion':
return { action: 'rebalance-suggestion', sessionId: remoteSessionId(value.sessionId) };
case 'rebalance-decision':
if (typeof value.remember !== 'boolean') invalidRemote('invalid remember');
return {
action: 'rebalance-decision',
sessionId: remoteSessionId(value.sessionId),
memberKey: remoteMemberKey(value.memberKey),
remember: value.remember as boolean,
...(value.clientId !== undefined ? { clientId: remoteSessionId(value.clientId) } : {}),
};
default:
invalidRemote('unknown provider group action');
}
}
/** 同账号电脑读组所在电脑 `pick` 的回包;格式不对按「没有组」处理。 */
export function parseProviderGroupRemotePick(raw: unknown, groupProviderId: string): ProviderGroupRemotePick {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { kind: 'none' };
const value = raw as Record<string, unknown>;
if (value.kind === 'unavailable') {
const limit = value.usageLimit as Partial<ProviderGroupUsageLimit> | null | undefined;
const reset = limit?.resetAtMs;
const valid = limit && (reset === null || (typeof reset === 'number' && Number.isSafeInteger(reset) && reset > 0));
return { kind: 'unavailable', ...(valid ? { usageLimit: { resetAtMs: reset } as ProviderGroupUsageLimit } : {}) };
}
if (value.kind !== 'member') return { kind: 'none' };
const member = normalizeMember(value.member, groupProviderId);
if (!member) return { kind: 'none' };
const label = normalizeLabel(value.label) ?? member.label ?? member.key;
return {
kind: 'member',
member: { key: member.key, kind: member.kind, agentDeviceId: member.agentDeviceId, providerId: member.providerId },
label,
};
}
/** 读任务所在电脑 `session-group` 的回包;格式不对按没归组处理。坐标仍是那台电脑视角。 */
export function parseProviderGroupRemoteSessionGroup(raw: unknown): ProviderGroupSessionGroup {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
const group = (raw as Record<string, unknown>).group;
if (!group || typeof group !== 'object' || Array.isArray(group)) return null;
const value = group as Record<string, unknown>;
const groupDeviceId = value.groupDeviceId ?? null;
if (groupDeviceId !== null && (
typeof groupDeviceId !== 'string'
|| !DEVICE_ID_PATTERN.test(groupDeviceId)
|| isProviderShareAgentDeviceId(groupDeviceId)
)) return null;
if (!isProviderGroupProviderId(value.providerId)) return null;
return { groupDeviceId, providerId: value.providerId };
}
const MEMBER_STATES: readonly ProviderGroupMemberState[] = ['available', 'full', 'paused', 'cooling', 'offline', 'unavailable'];
const UNAVAILABLE_REASONS: readonly ProviderGroupUnavailableReason[] = ['provider-off', 'disconnected', 'share-paused', 'share-removed'];
/** 同账号电脑读组所在电脑 `view` 的回包(设置页只读展示、发送前检查);坏条目丢弃。 */
export function parseProviderGroupRemoteView(raw: unknown, groupProviderId: string): ProviderGroupView {
const empty: ProviderGroupView = { providerId: groupProviderId, config: null, members: [] };
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return empty;
const value = raw as Record<string, unknown>;
const model = typeof value.model === 'string' && value.model.length > 0 && value.model.length <= 512
? value.model
: undefined;
const config = normalizeProviderGroupConfig(value.config, groupProviderId);
if (!config) return empty;
const keys = new Set(config.members.map((m) => m.key));
const count = (v: unknown, max: number) =>
typeof v === 'number' && Number.isFinite(v) ? Math.min(max, Math.max(0, Math.round(v))) : 0;
const members = (Array.isArray(value.members) ? value.members : []).flatMap((entry): ProviderGroupMemberStatus[] => {
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return [];
const item = entry as Record<string, unknown>;
const key = typeof item.key === 'string' && keys.has(item.key) ? item.key : null;
const state = MEMBER_STATES.includes(item.state as ProviderGroupMemberState) ? item.state as ProviderGroupMemberState : null;
const member = key ? config.members.find((m) => m.key === key)! : null;
if (!member || !state) return [];
const reason = UNAVAILABLE_REASONS.includes(item.reason as ProviderGroupUnavailableReason)
? item.reason as ProviderGroupUnavailableReason
: undefined;
const ownerName = normalizeLabel(item.ownerName);
// 旧组所在电脑不回账号名:用组设置里的快照,都没有时界面按第几个账号称呼。
const providerName = normalizeLabel(item.providerName) ?? member.providerName;
const appVersion = readProviderGroupAppVersion(item.appVersion);
const guestSupport = ['supported', 'needs-update', 'unknown'].includes(item.guestSupport as string)
? item.guestSupport as ProviderGroupGuestSupport : undefined;
const coolingUntil = typeof item.coolingUntil === 'number' && Number.isFinite(item.coolingUntil) ? item.coolingUntil : undefined;
// 分享来的电脑不读配额(provider-groups.md §5「分享边界」):回包里有也不收。
const quota = member.kind === 'share' ? undefined : readProviderGroupMemberQuota(item.quota);
const fiveHourTight = quota !== undefined && item.fiveHourTight === true;
return [{
key: member.key,
kind: member.kind,
label: normalizeLabel(item.label) ?? member.label ?? member.key,
...(providerName ? { providerName } : {}),
...(ownerName ? { ownerName } : {}),
...(appVersion ? { appVersion } : {}),
...(guestSupport ? { guestSupport } : {}),
state,
...(reason ? { reason } : {}),
running: count(item.running, 10_000),
limit: member.limit,
weight: member.weight,
paused: member.paused,
...(coolingUntil !== undefined ? { coolingUntil } : {}),
...(quota ? { quota } : {}),
...(fiveHourTight ? { fiveHourTight: true as const } : {}),
}];
});
return { providerId: groupProviderId, config, members, ...(model ? { model } : {}),
...(value.fastPolicyPending === true ? { fastPolicyPending: true } : {}) };
}