Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 远程 Agent(同账号):任务、项目文件与命令留在控制端(用户操作的电脑),Agent 进程跑在
* 被控端(提供 Agent 登录、订阅与供应商的电脑)。被控端用它自己的程序、登录与供应商配置
* 启动 Agent;读写文件、执行命令与 Cindy 工具经本通道回到控制端执行。
*
* 通信方向始终由控制端发起,被控端从不反过来控制控制端:
* - `open / call / reply / push / close`:控制端 → 被控端的指令与回复;
* - `poll`:控制端按游标拉取被控端的事件字节流(每行一个 JSON,见 RemoteAgentStreamItem)。
* 同一台被控端上的全部任务共用一个 poll(一次带上各任务的游标),任务再多也只占一个在途请求。
* Agent 事件、方法调用结果、被控端需要控制端处理的反向请求(权限确认、MCP 与执行器 HTTP、
* Codex exec-server WebSocket 帧)都在这条流里,读多快才发多快,不主动推送到共享 relay;
* - 大内容(带图片的消息、文件内容回复)先分段 `upload` 暂存,再由 open / call / reply 引用。
*
* 幂等:poll 按游标幂等,peer reset 后可重读;open 按 runId、call 按 callId、reply 按 requestId、
* push 按 seq 去重。除 read 外都不自动重试(结果不明时由上层按自身语义处理)。
*/
export const REMOTE_AGENT_CHANNEL = 'maker:remote-agent:v1';
export const REMOTE_AGENT_VERSION = 1;
export const REMOTE_AGENT_KINDS = ['claude-code', 'codex', 'pi'] as const;
export type RemoteAgentKind = (typeof REMOTE_AGENT_KINDS)[number];
/** 每段上传的原始字节(gzip 之后)。base64 后约 683KB,远低于单条逻辑消息 4MB 上限。 */
export const REMOTE_AGENT_UPLOAD_CHUNK_BYTES = 512 * 1024;
/** gzip 后单个暂存载荷上限。 */
export const REMOTE_AGENT_MAX_PAYLOAD_BYTES = 64 * 1024 * 1024;
export const REMOTE_AGENT_MAX_UPLOAD_CHUNKS =
REMOTE_AGENT_MAX_PAYLOAD_BYTES / REMOTE_AGENT_UPLOAD_CHUNK_BYTES;
/** 内联载荷(JSON 序列化后)上限;更大的走 upload。 */
export const REMOTE_AGENT_MAX_INLINE_PAYLOAD_CHARS = 1024 * 1024;
/** 单个任务一次 poll 最多返回的事件流字节。 */
export const REMOTE_AGENT_READ_MAX_BYTES = 512 * 1024;
/** 一次 poll 所有任务合计最多返回的字节(base64 后仍远低于单条逻辑消息 4MB)。 */
export const REMOTE_AGENT_POLL_MAX_BYTES = 1536 * 1024;
/** 没有新数据时被控端最多挂起 poll 的时长;远低于通道超时,留出回程余量。 */
export const REMOTE_AGENT_READ_WAIT_MS = 10_000;
/** 一次 poll 最多带的任务数。 */
export const REMOTE_AGENT_MAX_POLL_RUNS = 64;
export const REMOTE_AGENT_INVOKE_TIMEOUT_MS = 30_000;
/** 同一控制端在一台被控端上同时运行的远程 Agent 任务上限。 */
export const REMOTE_AGENT_MAX_RUNS_PER_CONTROLLER = 16;
/** 被控端设置的闲置收回时长上限(分钟,`caps.idleReclaimMinutes`)。 */
export const REMOTE_AGENT_IDLE_RECLAIM_MAX_MINUTES = 1440;
/** 一次 push 最多携带的 WebSocket 帧数。 */
export const REMOTE_AGENT_MAX_PUSH_FRAMES = 64;
/**
* 控制端可以调用的 Agent 会话方法(白名单)。与 maker-core AgentSessionHandle 同名;
* 不在表里的方法被控端一律拒绝。
*/
export const REMOTE_AGENT_METHODS = [
'send',
'steer',
'abort',
'requestGracefulStop',
'setModel',
'requiresModelSwitchRebuild',
'previewModelSwitch',
'setPermissionMode',
'setEffort',
'setFastMode',
'setPlanMode',
'setThinkingEnabled',
'setExtraDirs',
'setWritableDirs',
'setVendorOptions',
'stopBackgroundTask',
'resumeBackgroundTask',
'compactSession',
'getContextUsage',
'getCodexContextWindowInfo',
'useCindyAutoReviewFallback',
// 回到某条消息:对话在 Agent 那边截断(文件在控制端按保存点回退)。
'previewRewindFiles',
'commitRewindFiles',
] as const;
export type RemoteAgentMethod = (typeof REMOTE_AGENT_METHODS)[number];
export const REMOTE_AGENT_ERROR_CODES = [
'REMOTE_AGENT_INVALID',
'REMOTE_AGENT_NOT_FOUND',
'REMOTE_AGENT_UNSUPPORTED',
'REMOTE_AGENT_PEER_TOO_OLD',
'REMOTE_AGENT_BUSY',
'REMOTE_AGENT_EXPIRED',
'REMOTE_AGENT_ACCOUNT_CHANGED',
'REMOTE_AGENT_UNAVAILABLE',
// 那台电脑没有对这个供应商打开「允许被远程调用」(或已关闭)。
'REMOTE_AGENT_PROVIDER_NOT_ALLOWED',
// 供应商组转来的受邀者任务:这台电脑的主人没有同意这个受邀者经组使用(只回给打开时带了 reshareKey 的组所在电脑)。
'REMOTE_AGENT_RESHARE_NOT_ALLOWED',
// 那台电脑上的 Agent 分叉原生历史失败(电脑本身在线)。只回给分叉请求带了 acceptsForkFailed 的控制端,
// 旧控制端照旧收到 REMOTE_AGENT_UNAVAILABLE。
'REMOTE_AGENT_FORK_FAILED',
] as const;
export type RemoteAgentErrorCode = (typeof REMOTE_AGENT_ERROR_CODES)[number];
/** 内联 JSON 或引用已上传的 gzip(JSON) 分段。 */
export type RemoteAgentPayload =
| { json: unknown }
| { uploadId: string; chunks: number; bytes: number };
export interface RemoteAgentErrorInfo {
code: string;
message: string;
/** 原错误类名(仅用于控制端还原 maker-core 的特定错误类型)。 */
name?: string;
}
/** 被控端请控制端处理的反向请求。 */
export type RemoteAgentReverseRequest =
| { type: 'model-access'; model?: string }
| { type: 'interaction'; request: unknown }
| {
type: 'http';
/** 被控端隧道上的路由(如 `/exec/read`、`/mcp/cindy_memory`)。 */
method: string;
path: string;
headers: Array<[string, string]>;
/** base64 请求体。 */
body?: string;
}
| { type: 'callback'; name: RemoteAgentCallbackName; args: unknown[] };
export const REMOTE_AGENT_CALLBACKS = [
'onTranscriptUserEntry',
'onInvalidResumeSession',
'onInteractionStateChange',
] as const;
export type RemoteAgentCallbackName = (typeof REMOTE_AGENT_CALLBACKS)[number];
/** 控制端对反向请求的回复。 */
export type RemoteAgentReply =
| { type: 'interaction'; result: unknown }
| { type: 'http'; status: number; headers: Array<[string, string]>; body?: string }
| { type: 'callback'; value?: unknown }
| { type: 'error'; error: RemoteAgentErrorInfo };
/**
* 控制端发给被控端 WebSocket 连接的帧(Codex exec-server 隧道)。单帧过大的消息拆成多段,
* 除最后一段外都带 `more: true`,被控端拼好后再作为一条 WebSocket 消息发出。
*/
export interface RemoteAgentPushFrame {
connId: string;
kind: 'message' | 'close';
data?: string;
more?: true;
}
/** 一次 push 里所有帧数据的总长度上限(远低于单条逻辑消息 4MB)。 */
export const REMOTE_AGENT_MAX_PUSH_CHARS = 3 * 1024 * 1024;
export type RemoteAgentRequest =
| { op: 'caps' }
/** Same-account native history transfer. The host validates commands before accessing storage. */
| { op: 'native-history'; sessionId: string; command: unknown }
/** G→O: durable task location only; every use still needs a fresh allocation. */
| { op: 'direct-locate'; sessionId: string }
/** A shared guest asks the group owner to choose a same-account executor for a short-lived direct route. */
| { op: 'allocate'; agentKind: RemoteAgentKind; model: string; sessionId: string;
/** Renewal and model changes must stay on the executor holding this task. */
preferredExecutorDeviceId?: string }
/** Content-free running state for the group's load balancer; expires if reports stop. */
| { op: 'direct-status'; sessionId: string; running: boolean }
/** G releases only the exact allocation whose direct open failed; a later generation is untouched. */
| { op: 'direct-release'; sessionId: string; generation: string }
/** A direct guest asks O for its one-use group failover token after a machine-scoped failure. */
| { op: 'direct-switch'; sessionId: string }
/** Executor reports content-free metering to the group owner with an idempotency key. */
| { op: 'direct-usage'; shareId: string; memberId: string; guestDeviceId: string;
sessionId: string; generation: string; usageId: string; agentKind: RemoteAgentKind; samples: RemoteAgentUsageSample[] }
/** Authenticated same-account group owner installs or removes a guest grant on the executor. */
| { op: 'delegate'; action: 'grant' | 'revoke'; shareId: string; memberId: string; guestDeviceId: string;
providerId: string; model: string; sessionId: string; generation?: string; cleanupEpoch?: number }
/** Authenticated group owner updates only its own task speed constraints, never model grants. */
| ({ op: 'fast-policy' } & RemoteAgentFastPolicy)
| ({ op: 'fork' } & RemoteAgentForkRequest)
/** Native image recovery is scoped to the caller's task; never accepts file paths. */
| { op: 'images'; sessionId: string; relay?: string; action: 'list'; offset: number }
| { op: 'images'; sessionId: string; relay?: string; action: 'read'; imageId: string; offset: number }
| { op: 'images'; sessionId: string; relay?: string; action: 'release'; imageId: string }
| { op: 'upload'; uploadId: string; index: number; data: string }
| { op: 'open'; runId: string; agentKind: RemoteAgentKind; payload: RemoteAgentPayload }
| { op: 'call'; runId: string; callId: string; method: RemoteAgentMethod; payload: RemoteAgentPayload }
/**
* waitMs:没有新数据时最多挂起多久(缺省 READ_WAIT_MS)。控制端在已有一个长等待在途时,
* 可以再发一个 waitMs=0 的短 poll 立刻取新任务或刚触发的数据;两个 poll 返回的数据可能重叠,
* 控制端按 from 去重。
* hold:控制端这边还有这个任务的工作在进行、被控端看不到(如 Codex 经执行环境在控制端起的后台进程),
* 被控端按有活动处理,不按闲置收回。旧被控端忽略。
*/
| { op: 'poll'; runs: Array<{ runId: string; cursor: number; hold?: true }>; waitMs?: number }
| { op: 'reply'; runId: string; requestId: string; payload: RemoteAgentPayload }
/** hold: local work has started; protect it with the startup reply before the next poll batch. */
| { op: 'push'; runId: string; seq: number; frames: RemoteAgentPushFrame[]; hold?: true }
| { op: 'close'; runId: string; mode: 'close' | 'detach'; reason: RemoteAgentTeardownReason }
/**
* 供应商组(组所在电脑 → 组内电脑):组所在电脑删掉某个受邀者后,请组内电脑清掉替这个受邀者
* 运行过的任务留下的会话记录与目录。relay 是组所在电脑为受邀者取的不透明键(打开任务时随载荷带过来),
* 只作用于调用方自己的 relay。旧版组内电脑回 REMOTE_AGENT_INVALID(它从没接过被中转的任务)。
*/
| { op: 'forget'; relay: string }
/** O asks M to purge a direct G→M guest only when M has persisted O's verified delegation. */
| { op: 'forget'; directGuest: { shareId: string; memberId: string; guestDeviceId: string;
forgetId: string; cleanupEpoch: number } }
/**
* 供应商组转分享(组所在电脑 → 分享来的组内电脑,调用方是那台的受邀者):组所在电脑把自己分享的人
* 经组使用这台电脑的请求整体报上来(整体替换调用方上一份),那台的主人逐人同意。回包是每一项此刻的结果
* ({@link RemoteAgentReshareResult})。只发给 caps 声明了 reshareConsent 的电脑;支持大名单的电脑另声明
* reshareBatch,分片在最后一片到达前不会替换审批名单。
*/
| { op: 'reshare'; entries: RemoteAgentReshareEntry[]; batch?: RemoteAgentReshareBatch };
export interface RemoteAgentFastPolicy {
group: string;
revision: number;
allowFast: boolean;
/** Registration precedes opening the task; omitted for a group policy update. */
binding?: { sessionId: string; controllerDeviceId?: string; relay?: string;
/** Owner-approved direct guest task. The executor verifies its delegation before binding. */
providerShareGuest?: { shareId: string; memberId: string; guestDeviceId: string } };
}
/** 供应商组为受邀者取的不透明键(组所在电脑按受邀者派生,不含身份信息);「需要换一台」凭证同一格式。 */
export const REMOTE_AGENT_RELAY_KEY_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
/** 转分享批次 id 与 relay 一样是不透明的短键,不携带账号或成员身份。 */
export const REMOTE_AGENT_RESHARE_BATCH_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
/**
* 转分享请求里的一个人:组所在电脑分享的人(按账号,不分设备)。key 是组所在电脑按(分享, 成员)派生的不透明键,
* 打开中转任务时随载荷带上(reshareKey);昵称与头像由组所在电脑转述,只用来让那台的主人认出是谁。
*/
export interface RemoteAgentReshareEntry {
key: string;
name: string;
avatar?: string;
}
/** 大名单转分享的片段信息;每个片段仍受 REMOTE_AGENT_MAX_RESHARE_ENTRIES 限制。 */
export interface RemoteAgentReshareBatch {
id: string;
index: number;
count: number;
}
export type RemoteAgentReshareState = 'pending' | 'approved' | 'rejected';
export const REMOTE_AGENT_RESHARE_STATES: readonly RemoteAgentReshareState[] = ['pending', 'approved', 'rejected'];
export interface RemoteAgentReshareResult {
entries: Array<{ key: string; state: RemoteAgentReshareState }>;
/** 分块请求的回执;complete=false 时接收端尚未替换审批记录。 */
batch?: RemoteAgentReshareBatch & { complete: boolean };
}
/** 一次转分享请求最多带几个人(远高于实际分享人数,只用来挡异常请求)。 */
export const REMOTE_AGENT_MAX_RESHARE_ENTRIES = 256;
const RESHARE_NAME_MAX = 128;
const RESHARE_AVATAR_MAX = 2048;
/**
* 供应商组「需要换一台」:组所在电脑在中转任务的事件流里发出的状态键,值是一次性凭证。只发给打开任务时
* 声明了 acceptsGroupSwitch 的控制端,排在那次错误前面;控制端取走凭证、不并入任务状态。
*/
export const REMOTE_AGENT_GROUP_SWITCH_STATE_KEY = 'providerGroupSwitch';
/** 与 maker-core AgentSessionTeardownReason 同值。 */
export const REMOTE_AGENT_TEARDOWN_REASONS = ['navigation', 'account-boundary', 'app-quit'] as const;
export type RemoteAgentTeardownReason = (typeof REMOTE_AGENT_TEARDOWN_REASONS)[number];
/** Native fork control plane. Paths and guest storage are resolved by the host, never the caller. */
export interface RemoteAgentForkRequest {
sourceSessionId: string;
newSessionId: string;
agentKind: RemoteAgentKind;
sourceSdkSessionId: string;
model: string;
providerId?: string | null;
upToMessageId?: string;
lastTurnId?: string;
tailTurnsToDrop?: number;
forkAtTimestampMs?: number;
relay?: string;
reshareKey?: string;
/** 控制端认识 REMOTE_AGENT_FORK_FAILED。组所在电脑转发时原样带上受邀者的声明;旧被控端忽略。 */
acceptsForkFailed?: true;
}
export interface RemoteAgentForkResult {
newSdkSessionId: string;
uuidMap: Array<[string, string]>;
initialContextTokens?: number;
usedNativeForkAnchor?: boolean;
}
export interface RemoteAgentCaps {
/** Preserves external-application tools and runtime storage across every relay. */
localApplication?: boolean;
nativeHistoryTransfer?: boolean;
/** Executor accepts bounded same-account group-owner delegation for a shared guest. */
directGuestExecution?: boolean;
subscriptionFastPolicy?: true;
nativeFork?: boolean;
imageRecovery?: boolean;
imageRecoveryRelay?: boolean;
version: number;
agents: Array<{ kind: RemoteAgentKind; available: boolean }>;
maxRuns: number;
uploadChunkBytes: number;
maxPayloadBytes: number;
/** 是否支持 opaque 虚拟工作区;不支持时控制端必须拒绝启动以免泄露真实路径。 */
virtualWorkspace?: boolean;
/**
* 供应商组:能接受同账号组所在电脑中转过来的受邀者任务(打开时带 relay 键就按受邀者隔离运行)。
* 不声明的电脑,组所在电脑不给它分受邀者的任务(否则受邀者会拿到主人级权限)。
*/
guestRelay?: boolean;
/** Group relays can query the original member's live model grants before dispatch. */
relayModelAccess?: boolean;
/**
* 供应商组转分享:受邀者(组所在电脑)可以报上它分享的人、由这台的主人逐人同意(op `reshare`),组转来的受邀者任务
* 只在同意过的人上运行。不声明的电脑给不出同意,组所在电脑不把受邀者的任务分给它。
*/
reshareConsent?: boolean;
/** 是否支持带 batch 的转分享请求;未声明时只能使用单片旧协议。 */
reshareBatch?: boolean;
/**
* 这台电脑的主人设置的闲置收回时长(分钟,0 = 不收回):任务不忙且闲置满这么久,这台就结束它的 Agent 进程
* (事件流 `closed` 带 `idleReclaimed`)。旧版电脑不声明,也不收回。
*/
idleReclaimMinutes?: number;
}
export interface RemoteAgentReadResult {
/** 本次数据的起始偏移(缺省等于请求的游标)。并发 poll 时可能晚于请求的游标。 */
from?: number;
/** 本次返回数据之后的游标(事件流字节偏移)。 */
cursor: number;
/** base64 的事件流字节(NDJSON,可能在行中间截断,控制端按行拼接)。 */
data?: string;
/** 流已结束且全部读完。 */
done?: true;
}
/** poll 的结果:只列出有新数据、已结束或已不存在的任务。 */
export interface RemoteAgentPollResult {
runs: Array<RemoteAgentReadResult & { runId: string; missing?: true }>;
}
/** 事件流里的一行。 */
export type RemoteAgentStreamItem =
| { t: 'started'; handle: Record<string, unknown> }
| { t: 'start-failed'; error: RemoteAgentErrorInfo }
| { t: 'event'; event: unknown }
| { t: 'state'; state: Record<string, unknown> }
| { t: 'result'; callId: string; ok: true; value?: unknown }
| { t: 'result'; callId: string; ok: false; error: RemoteAgentErrorInfo }
| { t: 'request'; requestId: string; request: RemoteAgentReverseRequest }
/** 被控端放弃了一个尚未回包的反向请求(如 Agent 取消了工具调用),控制端应中止对应执行。 */
| { t: 'cancel'; requestId: string }
| { t: 'ws'; connId: string; kind: 'open' | 'message' | 'close'; path?: string; data?: string }
/**
* idleReclaimed:被控端按主人设置的时长收回了这个闲置任务(reason 写 `ended`)。新控制端只断开对方的 Agent
* 进程、保留本机部分,下次要它干活时带原来的会话 id 连回;旧控制端不认识这个字段,按 `ended` 静默收起,
* 下次发消息时重建任务并接回原来的对话。
*/
| { t: 'closed'; reason: string; error?: RemoteAgentErrorInfo; idleReclaimed?: true };
const ID = /^[0-9a-f-]{36}$/;
const CONN_ID = /^[A-Za-z0-9_-]{1,64}$/;
const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$/;
const MAX_HEADERS = 64;
const MAX_HEADER_VALUE = 8192;
const MAX_PATH = 2048;
const MAX_MESSAGE = 2048;
const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
function invalid(): never {
throw new Error('REMOTE_AGENT_INVALID');
}
function record(value: unknown): Record<string, unknown> {
if (!value || typeof value !== 'object' || Array.isArray(value)) invalid();
return value as Record<string, unknown>;
}
function id(value: unknown): string {
if (typeof value !== 'string' || !ID.test(value)) invalid();
return value;
}
export interface RemoteAgentUsageSample {
model: string; turns: number; inputTokens: number; outputTokens: number;
cacheReadTokens: number; cacheCreateTokens: number; sdkCostUsd: number;
}
function providerShareId(value: unknown): string {
if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) invalid();
return value;
}
function deviceId(value: unknown): string {
if (typeof value !== 'string' || !value || value.length > 128) invalid();
return value;
}
function count(value: unknown, max: number): number {
if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > max) invalid();
return value as number;
}
function reshareBatch(value: unknown): RemoteAgentReshareBatch {
const v = record(value);
if (typeof v.id !== 'string' || !REMOTE_AGENT_RESHARE_BATCH_ID_PATTERN.test(v.id)) invalid();
// 片数不是产品人数上限;实际接收端按字节预算限制暂存内容。
const batchCount = count(v.count, Number.MAX_SAFE_INTEGER);
if (batchCount < 1) invalid();
const index = count(v.index, batchCount - 1);
return { id: v.id, index, count: batchCount };
}
function reshareResultBatch(value: unknown): RemoteAgentReshareResult['batch'] {
const v = record(value);
const batch = reshareBatch(v);
if (typeof v.complete !== 'boolean') invalid();
return { ...batch, complete: v.complete };
}
function base64Chars(bytes: number): number {
return Math.ceil(bytes / 3) * 4;
}
function base64(value: unknown, maxBytes: number): string {
if (typeof value !== 'string' || value.length > base64Chars(maxBytes) || !BASE64.test(value)) invalid();
return value;
}
function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T {
if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) invalid();
return value as T;
}
function payload(value: unknown): RemoteAgentPayload {
const v = record(value);
if ('json' in v) {
// 内联载荷的大小由序列化后的长度约束;控制端发送前同样检查。
let size: number;
try {
size = JSON.stringify(v.json)?.length ?? 0;
} catch {
invalid();
}
if (size > REMOTE_AGENT_MAX_INLINE_PAYLOAD_CHARS) invalid();
return { json: v.json };
}
const chunks = count(v.chunks, REMOTE_AGENT_MAX_UPLOAD_CHUNKS);
const bytes = count(v.bytes, REMOTE_AGENT_MAX_PAYLOAD_BYTES);
if (chunks < 1 || bytes > chunks * REMOTE_AGENT_UPLOAD_CHUNK_BYTES) invalid();
return { uploadId: id(v.uploadId), chunks, bytes };
}
function pushFrames(value: unknown): RemoteAgentPushFrame[] {
if (!Array.isArray(value) || value.length === 0 || value.length > REMOTE_AGENT_MAX_PUSH_FRAMES) invalid();
let total = 0;
return value.map((item) => {
const frame = record(item);
if (typeof frame.connId !== 'string' || !CONN_ID.test(frame.connId)) invalid();
const kind = oneOf(frame.kind, ['message', 'close'] as const);
if (kind === 'message' && typeof frame.data !== 'string') invalid();
if (typeof frame.data === 'string' && frame.data.length > REMOTE_AGENT_MAX_INLINE_PAYLOAD_CHARS) invalid();
total += typeof frame.data === 'string' ? frame.data.length : 0;
if (total > REMOTE_AGENT_MAX_PUSH_CHARS) invalid();
if (frame.more !== undefined && (frame.more !== true || kind !== 'message')) invalid();
return {
connId: frame.connId,
kind,
...(typeof frame.data === 'string' ? { data: frame.data } : {}),
...(frame.more === true ? { more: true as const } : {}),
};
});
}
/** 被控端解析控制端请求;不合法一律抛 `REMOTE_AGENT_INVALID`。 */
export function parseRemoteAgentRequest(value: unknown): RemoteAgentRequest {
const v = record(value);
switch (v.op) {
case 'caps':
return { op: 'caps' };
case 'native-history': {
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)) invalid();
return { op: 'native-history', sessionId: v.sessionId as string, command: record(v.command) };
}
case 'direct-locate':
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)) invalid();
return { op: 'direct-locate', sessionId: v.sessionId };
case 'allocate':
if (typeof v.model !== 'string' || !v.model || v.model.length > 512 || v.model.includes('\0')) invalid();
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)) invalid();
return { op: 'allocate', agentKind: oneOf(v.agentKind, REMOTE_AGENT_KINDS), model: v.model, sessionId: v.sessionId,
...(v.preferredExecutorDeviceId === undefined ? {} : { preferredExecutorDeviceId: deviceId(v.preferredExecutorDeviceId) }) };
case 'direct-status':
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)
|| typeof v.running !== 'boolean') invalid();
return { op: 'direct-status', sessionId: v.sessionId, running: v.running };
case 'direct-release':
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)
|| typeof v.generation !== 'string' || !ID.test(v.generation)) invalid();
return { op: 'direct-release', sessionId: v.sessionId, generation: v.generation };
case 'direct-switch':
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)) invalid();
return { op: 'direct-switch', sessionId: v.sessionId };
case 'direct-usage': {
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)
|| typeof v.generation !== 'string' || !ID.test(v.generation)
|| typeof v.usageId !== 'string' || !ID.test(v.usageId)
|| !Array.isArray(v.samples) || !v.samples.length || v.samples.length > 64) invalid();
const samples = v.samples.map((item): RemoteAgentUsageSample => {
const sample = record(item);
if (typeof sample.model !== 'string' || !sample.model || sample.model.length > 512) invalid();
const counters = ['turns', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreateTokens', 'sdkCostUsd'] as const;
for (const key of counters) if (typeof sample[key] !== 'number' || !Number.isFinite(sample[key])
|| (sample[key] as number) < 0 || (sample[key] as number) > 1e15) invalid();
return { model: sample.model, turns: sample.turns as number, inputTokens: sample.inputTokens as number,
outputTokens: sample.outputTokens as number, cacheReadTokens: sample.cacheReadTokens as number,
cacheCreateTokens: sample.cacheCreateTokens as number, sdkCostUsd: sample.sdkCostUsd as number };
});
return { op: 'direct-usage', shareId: providerShareId(v.shareId), memberId: providerShareId(v.memberId),
guestDeviceId: deviceId(v.guestDeviceId), sessionId: v.sessionId, generation: v.generation,
usageId: v.usageId, agentKind: oneOf(v.agentKind, REMOTE_AGENT_KINDS), samples };
}
case 'delegate': {
const shareId = providerShareId(v.shareId);
const memberId = providerShareId(v.memberId);
const guestDeviceId = deviceId(v.guestDeviceId);
if (typeof v.providerId !== 'string' || !v.providerId || v.providerId.length > 256 || v.providerId.includes('\0')) invalid();
if (typeof v.model !== 'string' || !v.model || v.model.length > 512 || v.model.includes('\0')) invalid();
if (typeof v.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.sessionId)) invalid();
if (v.action === 'grant' && (typeof v.generation !== 'string' || !ID.test(v.generation))) invalid();
if (v.generation !== undefined && (typeof v.generation !== 'string' || !ID.test(v.generation))) invalid();
if (v.cleanupEpoch !== undefined) count(v.cleanupEpoch, Number.MAX_SAFE_INTEGER);
return { op: 'delegate', action: oneOf(v.action, ['grant', 'revoke'] as const), shareId, memberId, guestDeviceId,
providerId: v.providerId, model: v.model, sessionId: v.sessionId,
...(typeof v.generation === 'string' ? { generation: v.generation } : {}),
...(v.cleanupEpoch !== undefined ? { cleanupEpoch: v.cleanupEpoch as number } : {}) };
}
case 'fast-policy': {
if (typeof v.group !== 'string' || !/^[A-Za-z0-9_.:-]{1,256}$/.test(v.group)
|| typeof v.allowFast !== 'boolean') invalid();
let binding: RemoteAgentFastPolicy['binding'];
if (v.binding !== undefined) {
const b = record(v.binding);
if (typeof b.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(b.sessionId)) invalid();
if (b.controllerDeviceId !== undefined && (typeof b.controllerDeviceId !== 'string'
|| !/^[A-Za-z0-9_.-]{1,128}$/.test(b.controllerDeviceId))) invalid();
if (b.relay !== undefined && (typeof b.relay !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(b.relay))) invalid();
let providerShareGuest: { shareId: string; memberId: string; guestDeviceId: string } | undefined;
if (b.providerShareGuest !== undefined) {
const guest = record(b.providerShareGuest);
if (b.controllerDeviceId !== undefined || b.relay !== undefined
|| typeof guest.shareId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(guest.shareId)
|| typeof guest.memberId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(guest.memberId)
|| typeof guest.guestDeviceId !== 'string' || guest.guestDeviceId.length < 1
|| guest.guestDeviceId.length > 128) invalid();
providerShareGuest = { shareId: guest.shareId, memberId: guest.memberId, guestDeviceId: guest.guestDeviceId };
}
binding = { sessionId: b.sessionId as string,
...(typeof b.controllerDeviceId === 'string' ? { controllerDeviceId: b.controllerDeviceId } : {}),
...(typeof b.relay === 'string' ? { relay: b.relay } : {}),
...(providerShareGuest ? { providerShareGuest } : {}) };
}
return { op: 'fast-policy', group: v.group as string, allowFast: v.allowFast as boolean,
revision: count(v.revision, Number.MAX_SAFE_INTEGER), ...(binding ? { binding } : {}) };
}
case 'fork': {
const text = (value: unknown, max = 4096): string => {
if (typeof value !== 'string' || !value.length || value.length > max || value.includes('\0')) invalid();
return value as string;
};
const sessionId = (value: unknown): string => {
const valueText = text(value, 128);
if (!/^[A-Za-z0-9_-]+$/.test(valueText)) invalid();
return valueText;
};
const result: RemoteAgentForkRequest = {
sourceSessionId: sessionId(v.sourceSessionId),
newSessionId: sessionId(v.newSessionId),
agentKind: oneOf(v.agentKind, REMOTE_AGENT_KINDS),
sourceSdkSessionId: text(v.sourceSdkSessionId),
model: text(v.model, 512),
};
for (const key of ['upToMessageId', 'lastTurnId'] as const) {
if (v[key] !== undefined) result[key] = text(v[key], 256);
}
if (v.providerId !== undefined) result.providerId = v.providerId === null ? null : text(v.providerId, 512);
for (const key of ['relay', 'reshareKey'] as const) {
if (v[key] !== undefined) {
const value = text(v[key], 64);
if (!REMOTE_AGENT_RELAY_KEY_PATTERN.test(value)) invalid();
result[key] = value;
}
}
if (v.tailTurnsToDrop !== undefined) result.tailTurnsToDrop = count(v.tailTurnsToDrop, Number.MAX_SAFE_INTEGER);
if (v.forkAtTimestampMs !== undefined) result.forkAtTimestampMs = count(v.forkAtTimestampMs, Number.MAX_SAFE_INTEGER);
if (v.acceptsForkFailed === true) result.acceptsForkFailed = true;
if (result.sourceSessionId === result.newSessionId) invalid();
return { op: 'fork', ...result };
}
case 'images': {
// Same task-id contract as the open payload, including non-UUID internal tasks.
const sessionId = v.sessionId;
if (typeof sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) invalid();
if (v.relay !== undefined && (typeof v.relay !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(v.relay))) invalid();
const relay = typeof v.relay === 'string' ? { relay: v.relay } : {};
const action = oneOf(v.action, ['list', 'read', 'release'] as const);
if (action === 'list') return { op: 'images', sessionId, ...relay, action, offset: count(v.offset ?? 0, Number.MAX_SAFE_INTEGER) };
if (typeof v.imageId !== 'string' || !/^[a-f0-9]{64}$/.test(v.imageId)) invalid();
if (action === 'release') return { op: 'images', sessionId, ...relay, action, imageId: v.imageId as string };
return { op: 'images', sessionId, ...relay, action, imageId: v.imageId as string, offset: count(v.offset, Number.MAX_SAFE_INTEGER) };
}
case 'upload':
return {
op: 'upload',
uploadId: id(v.uploadId),
index: count(v.index, REMOTE_AGENT_MAX_UPLOAD_CHUNKS - 1),
data: base64(v.data, REMOTE_AGENT_UPLOAD_CHUNK_BYTES),
};
case 'open':
return {
op: 'open',
runId: id(v.runId),
agentKind: oneOf(v.agentKind, REMOTE_AGENT_KINDS),
payload: payload(v.payload),
};
case 'call':
return {
op: 'call',
runId: id(v.runId),
callId: id(v.callId),
method: oneOf(v.method, REMOTE_AGENT_METHODS),
payload: payload(v.payload),
};
case 'poll': {
if (!Array.isArray(v.runs) || v.runs.length === 0 || v.runs.length > REMOTE_AGENT_MAX_POLL_RUNS) invalid();
const runs = v.runs.map((item) => {
const entry = record(item);
return {
runId: id(entry.runId),
cursor: count(entry.cursor, Number.MAX_SAFE_INTEGER),
...(entry.hold === true ? { hold: true as const } : {}),
};
});
if (new Set(runs.map((run) => run.runId)).size !== runs.length) invalid();
return {
op: 'poll',
runs,
...(v.waitMs !== undefined ? { waitMs: count(v.waitMs, REMOTE_AGENT_READ_WAIT_MS) } : {}),
};
}
case 'reply':
return { op: 'reply', runId: id(v.runId), requestId: id(v.requestId), payload: payload(v.payload) };
case 'push':
return {
op: 'push', runId: id(v.runId), seq: count(v.seq, Number.MAX_SAFE_INTEGER), frames: pushFrames(v.frames),
...(v.hold === true ? { hold: true as const } : {}),
};
case 'close':
return {
op: 'close',
runId: id(v.runId),
mode: oneOf(v.mode, ['close', 'detach'] as const),
reason: oneOf(v.reason, REMOTE_AGENT_TEARDOWN_REASONS),
};
case 'forget':
if (v.directGuest !== undefined) {
if (v.relay !== undefined) invalid();
const guest = record(v.directGuest);
return { op: 'forget', directGuest: {
shareId: providerShareId(guest.shareId), memberId: providerShareId(guest.memberId),
guestDeviceId: deviceId(guest.guestDeviceId), forgetId: id(guest.forgetId),
cleanupEpoch: count(guest.cleanupEpoch, Number.MAX_SAFE_INTEGER),
} };
}
if (typeof v.relay !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(v.relay)) invalid();
return { op: 'forget', relay: v.relay };
case 'reshare': {
if (!Array.isArray(v.entries) || v.entries.length > REMOTE_AGENT_MAX_RESHARE_ENTRIES) invalid();
const entries = v.entries.map(reshareEntry);
if (new Set(entries.map((entry) => entry.key)).size !== entries.length) invalid();
return {
op: 'reshare',
entries,
...(v.batch === undefined ? {} : { batch: reshareBatch(v.batch) }),
};
}
default:
invalid();
}
}
function reshareEntry(value: unknown): RemoteAgentReshareEntry {
const v = record(value);
if (typeof v.key !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(v.key)) invalid();
const name = typeof v.name === 'string' ? v.name.trim() : '';
// eslint-disable-next-line no-control-regex -- 控制字符是显式拒绝目标
if (!name || name.length > RESHARE_NAME_MAX || /[\u0000-\u001f\u007f]/.test(name)) invalid();
const avatar = reshareAvatar(v.avatar);
return { key: v.key, name, ...(avatar ? { avatar } : {}) };
}
/** 头像只收 https 地址;其他写法丢掉(不让整条请求失败)。 */
function reshareAvatar(value: unknown): string | null {
if (typeof value !== 'string' || !value || value.length > RESHARE_AVATAR_MAX) return null;
try {
return new URL(value).protocol === 'https:' ? value : null;
} catch {
return null;
}
}
/** 组所在电脑读 `reshare` 的回包:不认识的状态、不在请求里的键丢掉。 */
export function parseRemoteAgentReshareResult(value: unknown, keys?: ReadonlySet<string>): RemoteAgentReshareResult {
const v = record(value);
if (!Array.isArray(v.entries) || v.entries.length > REMOTE_AGENT_MAX_RESHARE_ENTRIES) invalid();
const entries: RemoteAgentReshareResult['entries'] = [];
const seen = new Set<string>();
for (const item of v.entries) {
const entry = item && typeof item === 'object' && !Array.isArray(item) ? item as Record<string, unknown> : null;
if (!entry || typeof entry.key !== 'string' || !REMOTE_AGENT_RELAY_KEY_PATTERN.test(entry.key)) continue;
if (seen.has(entry.key)) invalid();
seen.add(entry.key);
if (keys && !keys.has(entry.key)) continue;
if (!(REMOTE_AGENT_RESHARE_STATES as readonly unknown[]).includes(entry.state)) continue;
entries.push({ key: entry.key, state: entry.state as RemoteAgentReshareState });
}
return {
entries,
...(v.batch === undefined ? {} : { batch: reshareResultBatch(v.batch) }),
};
}
/** poll 按游标幂等:peer reset 后可以重读,其余 op 不可重试。 */
export function isRemoteAgentReadInvoke(channel: string, args: unknown[] | undefined): boolean {
if (channel !== REMOTE_AGENT_CHANNEL) return false;
const request = args?.[0];
return !!request && typeof request === 'object' && (request as { op?: unknown }).op === 'poll';
}
// ─── 控制端解析被控端回包(对端可能是不同版本,按最小合同防御)───────────────
/** 控制端接受的单次 read 数据上限:高于本版本的 READ_MAX_BYTES,给新版被控端留余量。 */
const READ_RESULT_ACCEPT_BYTES = 2 * 1024 * 1024;
export function parseRemoteAgentForkResult(value: unknown): RemoteAgentForkResult {
const v = record(value);
const text = (value: unknown): value is string =>
typeof value === 'string' && value.length > 0 && value.length <= 4096 && !value.includes('\0');
if (!text(v.newSdkSessionId) || !Array.isArray(v.uuidMap) || v.uuidMap.length > 100_000) invalid();
const uuidMap: Array<[string, string]> = (v.uuidMap as unknown[]).map((pair) => {
if (!Array.isArray(pair) || pair.length !== 2 || !text(pair[0]) || !text(pair[1])) invalid();
return [pair[0], pair[1]];
});
return {
newSdkSessionId: v.newSdkSessionId as string,
uuidMap,
...(v.initialContextTokens !== undefined ? { initialContextTokens: count(v.initialContextTokens, Number.MAX_SAFE_INTEGER) } : {}),
...(v.usedNativeForkAnchor === true ? { usedNativeForkAnchor: true } : {}),
};
}
export function parseRemoteAgentCaps(value: unknown): RemoteAgentCaps {
const v = record(value);
const agents = Array.isArray(v.agents)
? v.agents.flatMap((item) => {
const entry = item && typeof item === 'object' ? item as Record<string, unknown> : null;
if (!entry || !(REMOTE_AGENT_KINDS as readonly unknown[]).includes(entry.kind)) return [];
return [{ kind: entry.kind as RemoteAgentKind, available: entry.available === true }];
})
: [];
const caps = {
version: count(v.version, 1_000),
agents,
maxRuns: count(v.maxRuns, 1_000),
uploadChunkBytes: count(v.uploadChunkBytes, REMOTE_AGENT_UPLOAD_CHUNK_BYTES),
maxPayloadBytes: count(v.maxPayloadBytes, Number.MAX_SAFE_INTEGER),
...(v.virtualWorkspace === true ? { virtualWorkspace: true } : {}),
...(v.localApplication === true ? { localApplication: true } : {}),
...(v.nativeFork === true ? { nativeFork: true } : {}),
...(v.nativeHistoryTransfer === true ? { nativeHistoryTransfer: true } : {}),
...(v.imageRecovery === true ? { imageRecovery: true } : {}),
...(v.imageRecoveryRelay === true ? { imageRecoveryRelay: true } : {}),
...(v.guestRelay === true ? { guestRelay: true } : {}),
...(v.directGuestExecution === true ? { directGuestExecution: true } : {}),
...(v.relayModelAccess === true ? { relayModelAccess: true } : {}),
...(v.reshareConsent === true ? { reshareConsent: true } : {}),
...(v.reshareBatch === true ? { reshareBatch: true } : {}),
// 可选能力:不合法时当作没声明,不让整个 caps 作废。
...(Number.isSafeInteger(v.idleReclaimMinutes) && (v.idleReclaimMinutes as number) >= 0
&& (v.idleReclaimMinutes as number) <= REMOTE_AGENT_IDLE_RECLAIM_MAX_MINUTES
? { idleReclaimMinutes: v.idleReclaimMinutes as number } : {}),
...(v.subscriptionFastPolicy === true ? { subscriptionFastPolicy: true as const } : {}),
};
if (caps.version < 1 || caps.maxRuns < 1 || caps.uploadChunkBytes < 1) invalid();
return caps;
}
export function parseRemoteAgentReadResult(value: unknown): RemoteAgentReadResult {
const v = record(value);
const result: RemoteAgentReadResult = { cursor: count(v.cursor, Number.MAX_SAFE_INTEGER) };
if (v.from !== undefined) {
result.from = count(v.from, Number.MAX_SAFE_INTEGER);
if (result.from > result.cursor) invalid();
}
if (v.data !== undefined) result.data = base64(v.data, READ_RESULT_ACCEPT_BYTES);
if (v.done !== undefined) {
if (v.done !== true) invalid();
result.done = true;
}
return result;
}
export function parseRemoteAgentPollResult(value: unknown): RemoteAgentPollResult {
const v = record(value);
if (!Array.isArray(v.runs) || v.runs.length > REMOTE_AGENT_MAX_POLL_RUNS) invalid();
return {
runs: v.runs.map((item) => {
const entry = record(item);
return {
runId: id(entry.runId),
...parseRemoteAgentReadResult(entry),
...(entry.missing === true ? { missing: true as const } : {}),
};
}),
};
}
function errorInfo(value: unknown): RemoteAgentErrorInfo {
const v = record(value);
return {
code: typeof v.code === 'string' ? v.code.slice(0, 128) : 'INTERNAL',
message: typeof v.message === 'string' ? v.message.slice(0, MAX_MESSAGE) : '',
...(typeof v.name === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(v.name) ? { name: v.name } : {}),
};
}
function headerList(value: unknown): Array<[string, string]> {
if (!Array.isArray(value) || value.length > MAX_HEADERS) invalid();
return value.map((entry) => {
if (!Array.isArray(entry) || entry.length !== 2) invalid();
const [name, headerValue] = entry as unknown[];
if (typeof name !== 'string' || !HEADER_NAME.test(name)) invalid();
if (typeof headerValue !== 'string' || headerValue.length > MAX_HEADER_VALUE || /[\r\n\0]/.test(headerValue)) invalid();
return [name, headerValue] as [string, string];
});
}
function reverseRequest(value: unknown): RemoteAgentReverseRequest {
const v = record(value);
switch (v.type) {
case 'model-access':
if (v.model !== undefined && (typeof v.model !== 'string' || !v.model || v.model.length > 512)) invalid();
return { type: 'model-access', ...(typeof v.model === 'string' ? { model: v.model } : {}) };
case 'interaction':
return { type: 'interaction', request: v.request };
case 'http': {
if (typeof v.method !== 'string' || !/^[A-Z]{3,7}$/.test(v.method)) invalid();
if (typeof v.path !== 'string' || !v.path.startsWith('/') || v.path.length > MAX_PATH || /[\s\0]/.test(v.path)) invalid();
return {
type: 'http',
method: v.method,
path: v.path,
headers: headerList(v.headers),
...(v.body !== undefined ? { body: base64(v.body, REMOTE_AGENT_MAX_PAYLOAD_BYTES) } : {}),
};
}
case 'callback':
return {
type: 'callback',
name: oneOf(v.name, REMOTE_AGENT_CALLBACKS),
args: Array.isArray(v.args) ? v.args : [],
};
default:
invalid();
}
}
/**
* 控制端解析事件流的一行。不认识的行类型返回 null(新版被控端可能新增类型,旧控制端跳过),
* 已知类型但字段不合法时抛 `REMOTE_AGENT_INVALID`。
*/
export function parseRemoteAgentStreamItem(line: string): RemoteAgentStreamItem | null {
let parsed: unknown;
try {
parsed = JSON.parse(line);
} catch {
invalid();
}
const v = record(parsed);
switch (v.t) {
case 'started':
return { t: 'started', handle: record(v.handle) };
case 'start-failed':
return { t: 'start-failed', error: errorInfo(v.error) };
case 'event':
return { t: 'event', event: v.event };
case 'state':
return { t: 'state', state: record(v.state) };
case 'result':
return v.ok === true
? { t: 'result', callId: id(v.callId), ok: true, ...(v.value !== undefined ? { value: v.value } : {}) }
: { t: 'result', callId: id(v.callId), ok: false, error: errorInfo(v.error) };
case 'request':
return { t: 'request', requestId: id(v.requestId), request: reverseRequest(v.request) };
case 'cancel':
return { t: 'cancel', requestId: id(v.requestId) };
case 'ws': {
if (typeof v.connId !== 'string' || !CONN_ID.test(v.connId)) invalid();
const kind = oneOf(v.kind, ['open', 'message', 'close'] as const);
return {
t: 'ws',
connId: v.connId,
kind,
...(typeof v.path === 'string' && v.path.length <= MAX_PATH ? { path: v.path } : {}),
...(typeof v.data === 'string' ? { data: v.data } : {}),
};
}
case 'closed':
return {
t: 'closed',
reason: typeof v.reason === 'string' ? v.reason.slice(0, 128) : 'unknown',
...(v.error !== undefined ? { error: errorInfo(v.error) } : {}),
...(v.idleReclaimed === true ? { idleReclaimed: true as const } : {}),
};
default:
return null;
}
}
/** 被控端校验控制端对反向请求的回复。 */
export function parseRemoteAgentReply(value: unknown): RemoteAgentReply {
const v = record(value);
switch (v.type) {
case 'interaction':
return { type: 'interaction', result: v.result };
case 'http': {
const status = count(v.status, 599);
if (status < 100) invalid();
return {
type: 'http',
status,
headers: headerList(v.headers),
...(v.body !== undefined ? { body: base64(v.body, REMOTE_AGENT_MAX_PAYLOAD_BYTES) } : {}),
};
}
case 'callback':
return { type: 'callback', ...(v.value !== undefined ? { value: v.value } : {}) };
case 'error':
return { type: 'error', error: errorInfo(v.error) };
default:
invalid();
}
}
/** 从 `[CODE] message` 形式的 IPC 错误里取出远程 Agent 错误码。 */
export function remoteAgentErrorCode(message: string | undefined): RemoteAgentErrorCode | null {
const code = /\[(REMOTE_AGENT_[A-Z_]+)\]/.exec(message ?? '')?.[1];
return code && (REMOTE_AGENT_ERROR_CODES as readonly string[]).includes(code)
? (code as RemoteAgentErrorCode)
: null;
}