Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* useAgentCapabilities — 按需拉取 maker-core 暴露的 agent capabilities。
*
* 设计:
* - 每个 agentKind 一份缓存 (module-scoped Map), 同 kind 第二次调用直接命中
* - 拉取过程暴露 loading/error 给调用方决定 fallback
* - 大部分 capability 静态;目录模型在 Codex 鉴权 / discovery 变化后原子刷新本地缓存
*
* 用法:
* const { capabilities } = useAgentCapabilities('claude-code');
* capabilities?.availableModels.map(...);
*/
import { useEffect, useState } from 'react';
import { createLogger } from '@/lib/logger';
import type { Effort, PermissionMode } from '@/lib/userPreferences.types';
const log = createLogger('useAgentCapabilities');
export type AgentKind = 'claude-code' | 'codex' | 'pi';
// capability 生命周期(预取 / 驱逐通知 / 本地快照刷新 / 启动预载)必须覆盖全部 agent,
// 少一个就会让该 agent 的远程会话在断链或 provider revision 后收不到 loading 事件、
// 也不再被重新预取,界面永久停在旧模型/能力快照(codex review)。新增 agent 只改这里。
const ALL_AGENT_KINDS = ['claude-code', 'codex', 'pi'] as const;
// renderer 视角: id 全部是不透明 string, 渲染只读 displayName。
// effort 的合法 id 集合 = capabilities.effortLevels 上每个项的 id。
export interface ModelDescriptor {
id: string;
displayName: string;
/** 目录分组 id(如 'gpt-budget'): 折扣版与官方版 displayName 同名, 靠它区分。 */
group?: string;
/**
* Gateway 原生 mode(issue #882)。availableModels 派生时已经过 isChatEligible
* 过滤,这里透传只是让下游按 model 二次分类的逻辑(如 resolveSourceSwitch 的
* classifyModel)拿到 mode,不必回读目录(2026-07 review)。
*/
mode?: string;
description?: string;
contextWindow: number;
efforts: readonly Effort[];
/** true = the catalog has not declared this model's effort capability yet. */
effortsUnknown?: boolean;
effortDisplayNames?: Partial<Record<Effort, string>>;
defaultEffort: Effort | null;
supportsFastMode?: boolean;
supportsUltrafastMode?: boolean;
/** 目录展示排序权重;缺省排末尾。 */
sortOrder?: number;
/**
* 选择器里默认是否可见(源自目录 defaultEnabled,缺省 ⇒ 可见)。
* 消费点见 modelDefinitions.getDefaultModelForVendor:种子默认只从默认可见的模型里取。
*/
defaultEnabled?: boolean;
/**
* 该模型是哪些 wire agent 的**新对话默认种子**(源自目录 newSessionDefault,与 sortOrder
* 解耦;生产环境 XD 网关由服务端按区域下发)。消费点见 modelDefinitions.newSessionDefaultModelId
* 与 draftModelCalibration:被标记且可用的模型优先作新对话默认。
*/
newSessionDefault?: ('claude-code' | 'codex' | 'pi')[];
}
export interface EffortDescriptor {
id: Effort;
displayName: string;
description?: string;
}
export interface PermissionModeDescriptor {
id: PermissionMode;
displayName: string;
description?: string;
}
/**
* CapabilityStatus 与 maker-core Capabilities['fork'/'rewind'] 同形,
* 让 UI 直接判 supported 决定 icon 显示。
*/
export type CapabilityStatus =
| { supported: true }
| {
supported: false;
reason?: 'sdk-missing' | 'not-implemented' | 'platform-limited';
upstreamRef?: string;
message?: string;
};
export interface AgentCapabilities {
availableModels: ModelDescriptor[];
/** Agent 是否实现 Fast Mode 运行时能力。 */
hasFastMode: boolean;
effortLevels: EffortDescriptor[];
permissionModes: PermissionModeDescriptor[];
/**
* 计划模式一级开关(composer「+」菜单入口)据此显示 / 隐藏。
* device-link 老被控端序列化的 capabilities 无此字段 → undefined = 不支持。
*/
planMode?: CapabilityStatus;
/**
* 会话级外部可写目录能力。device-link 老被控端无此字段 → undefined = 不支持,
* 控制端必须隐藏会触发新 channel 的入口。
*/
writableDirs?: CapabilityStatus;
/** Session fork — UserMessage 下方 Fork icon 据此显示 / 隐藏。 */
fork?: CapabilityStatus;
/** Session rewind — UserMessage 下方 Rewind icon 据此显示 / 隐藏。 */
rewind?: CapabilityStatus;
/**
* 同会话跨引擎切换(Claude Code ↔ Codex)。host 级能力,两个 agent 的 capabilities
* 都带回同一个值;device-link 老被控端无此字段 → undefined = 不支持,控制端隐藏
* 模型选择器顶部的 Agent 分段(它同时也没收录切换 channel,点了必失败)。
*/
supportsSessionAgentSwitch?: boolean;
/**
* 同引擎重选是否返回可供 SET_MODEL 二次校验的 CAS 修订号。首版切换 host 只有上面的
* 基础能力位;远程控制端必须同时看到本位才开放入口,避免旧 host 的清除回流先于 ack
* 到达时无法安全关联后续模型写入。
*/
supportsSessionAgentSwitchCas?: boolean;
/**
* 被控端是否支持在开启 Orca Team 时显式设置 Worker 默认权限。
* device-link 老被控端无此字段 → undefined,控制端必须阻止开启协同并提示升级。
*/
supportsOrcaWorkerPermissionMode?: boolean;
/**
* 被控端是否支持创建后修改 Worker 的角色名/标识(maker:worker:update)。
* device-link 老被控端无此字段 → undefined,控制端对远程 Worker 隐藏编辑入口。
*/
supportsOrcaWorkerUpdate?: boolean;
/** 被控端支持把 UI initial_task 延后到 Lead 首条输入 accepted 后派发。 */
supportsDeferredOrcaUiAssignment?: boolean;
/**
* 被控端支持给协同 Worker 单独指定 Agent 所在电脑(远程供应商,`agentDeviceId`)。
* 老被控端无此字段 → undefined:Worker 面板不列远程供应商、不发这个字段(老端会静默丢掉)。
*/
supportsOrcaWorkerAgentDevice?: boolean;
/**
* 手动压缩会话上下文能力(pi 原生 compact)。与 maker-core Capabilities.manualCompact
* 同形;device-link 老被控端序列化的 capabilities 无此字段 → undefined = 不支持。
* 上下文环压缩入口据此判定(见 resolveManualCompactChannel),不再硬编码 agentKind 列表。
*/
manualCompact?: CapabilityStatus;
/**
* 每轮 host 权限策略能力门:未声明或 supported.supported !== true 的 Agent 无法
* 用于「无条件挂逐条权限确认」的渠道(如个人微信)。与 maker-core 的
* Capabilities.turnPermissionPolicy 同构;device-link 老被控端无此字段 →
* undefined = 不支持。
*/
turnPermissionPolicy?: {
supported: CapabilityStatus;
unsupportedPermissionModes: string[];
};
}
/**
* 可写目录回调的跨端兼容门:本地沿用既有能力,SSH 等待远端 picker,device-link
* 只信任当前被控端明确声明的能力。缺字段、加载中与不支持都 fail closed。
*/
export function canExposeWritableDirsChange(options: {
capabilities: Pick<AgentCapabilities, 'writableDirs'> | null | undefined;
deviceId: string | null | undefined;
remoteHostId: string | null | undefined;
}): boolean {
if (options.remoteHostId != null) return false;
return options.deviceId == null || options.capabilities?.writableDirs?.supported === true;
}
/**
* 手动压缩调用通道判定 —— 上下文环压缩入口与请求分流的唯一判据(#1927 / #1933 review):
* - 真实 Claude Code 会话 → `claude-input`(输入协调器 maker:input:compact,SDK 斜杠命令通道);
* - 其余 agent 声明 manualCompact.supported(当前仅 pi)→ `compact-session`
* (capability-aware 通用通道 maker:compact-session,本地 IPC / device-link 隧道均可路由);
* - 其余(Codex 等无手动压缩能力)→ null = 无入口。
* 刻意不按 agentKind 扩排除列表:新 agent 只需在 maker-core 声明能力即可自动接入。
*/
export type CompactChannel = 'claude-input' | 'compact-session';
export function resolveManualCompactChannel(
agentKind: AgentKind | null | undefined,
capabilities: Pick<AgentCapabilities, 'manualCompact'> | null | undefined,
): CompactChannel | null {
if (agentKind === 'claude-code') return 'claude-input';
if (capabilities?.manualCompact?.supported) return 'compact-session';
return null;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return !!value && typeof value === 'object' && !Array.isArray(value);
}
function isStringArray(value: unknown): value is string[] {
return Array.isArray(value) && value.every((item) => typeof item === 'string');
}
function isOptionalString(value: unknown): boolean {
return value === undefined || typeof value === 'string';
}
function isOptionalBoolean(value: unknown): boolean {
return value === undefined || typeof value === 'boolean';
}
/** CapabilityStatus 形状校验(与 maker-core types/capabilities.ts 对齐)。 */
function isCapabilityStatus(value: unknown): boolean {
if (!isRecord(value)) return false;
// supported 必须是布尔;两种分支下可选字段统一只接受 string(undefined 允许)。
if (typeof value.supported !== 'boolean') return false;
return (
(value.reason === undefined || typeof value.reason === 'string') &&
(value.upstreamRef === undefined || typeof value.upstreamRef === 'string') &&
(value.message === undefined || typeof value.message === 'string')
);
}
function isOptionalCapabilityStatus(value: unknown): boolean {
return value === undefined || isCapabilityStatus(value);
}
function isOptionalFiniteNumber(value: unknown): boolean {
return value === undefined || (typeof value === 'number' && Number.isFinite(value));
}
function isOptionalStringRecord(value: unknown): boolean {
return (
value === undefined ||
(isRecord(value) && Object.values(value).every((label) => typeof label === 'string'))
);
}
/** 与 protocol newSessionDefault 约束一致:可选;存在时非空、已知 agent、无重复。 */
function isOptionalNewSessionDefault(value: unknown): boolean {
if (value === undefined) return true;
if (!Array.isArray(value) || value.length === 0) return false;
if (
value.some(
(agent) => agent !== 'claude-code' && agent !== 'codex' && agent !== 'pi',
)
) {
return false;
}
return new Set(value).size === value.length;
}
function isModelDescriptor(value: unknown): value is ModelDescriptor {
if (!isRecord(value)) return false;
const efforts = value.efforts;
const defaultEffort = value.defaultEffort;
return (
typeof value.id === 'string' &&
value.id.length > 0 &&
typeof value.displayName === 'string' &&
value.displayName.length > 0 &&
typeof value.contextWindow === 'number' &&
Number.isFinite(value.contextWindow) &&
value.contextWindow > 0 &&
isStringArray(efforts) &&
(defaultEffort === null ||
(typeof defaultEffort === 'string' && efforts.includes(defaultEffort))) &&
isOptionalBoolean(value.effortsUnknown) &&
isOptionalString(value.group) &&
isOptionalString(value.mode) &&
isOptionalString(value.description) &&
isOptionalStringRecord(value.effortDisplayNames) &&
isOptionalBoolean(value.supportsFastMode) &&
isOptionalFiniteNumber(value.sortOrder) &&
isOptionalBoolean(value.defaultEnabled) &&
isOptionalNewSessionDefault(value.newSessionDefault)
);
}
function isNamedDescriptor(value: unknown): boolean {
return (
isRecord(value) &&
typeof value.id === 'string' &&
value.id.length > 0 &&
typeof value.displayName === 'string' &&
value.displayName.length > 0 &&
isOptionalString(value.description)
);
}
function parseAgentCapabilities(value: unknown): AgentCapabilities {
if (!isRecord(value)) {
throw new Error('Invalid agent capabilities response');
}
if (!Array.isArray(value.availableModels)) {
throw new Error('Invalid agent capabilities response');
}
// Same policy as the local model plane: drop a catalog row that cannot
// stand on its own (missing defaultEffort, extra junk) instead of
// rejecting the whole remote list. One stale model on the controlled
// machine was emptying the selector.
value.availableModels = value.availableModels.filter(isModelDescriptor);
if (
typeof value.hasFastMode !== 'boolean' ||
!Array.isArray(value.effortLevels) ||
!value.effortLevels.every(isNamedDescriptor) ||
!Array.isArray(value.permissionModes) ||
!value.permissionModes.every(isNamedDescriptor) ||
!isOptionalBoolean(value.supportsSessionAgentSwitch) ||
!isOptionalBoolean(value.supportsSessionAgentSwitchCas) ||
!isOptionalBoolean(value.supportsOrcaWorkerPermissionMode) ||
!isOptionalBoolean(value.supportsOrcaWorkerUpdate) ||
!isOptionalBoolean(value.supportsDeferredOrcaUiAssignment) ||
!isOptionalBoolean(value.supportsOrcaWorkerAgentDevice) ||
!isOptionalCapabilityStatus(value.writableDirs) ||
!isOptionalCapabilityStatus(value.manualCompact)
) {
throw new Error('Invalid agent capabilities response');
}
return value as unknown as AgentCapabilities;
}
interface MakerApiShape {
getCapabilities: (agentKind: AgentKind) => Promise<AgentCapabilities>;
}
interface DeviceLinkShape {
invoke: (deviceId: string, channel: string, args: unknown[]) => Promise<unknown>;
}
function getMakerApi(): MakerApiShape | null {
const api = (
window as unknown as {
electronAPI?: { maker?: MakerApiShape };
}
).electronAPI?.maker;
return api ?? null;
}
function getDeviceLink(): DeviceLinkShape | null {
const dl = (
window as unknown as {
electronAPI?: { deviceLink?: DeviceLinkShape };
}
).electronAPI?.deviceLink;
return dl ?? null;
}
// device-link「以被控端为准」:远程会话的能力必须来自被控端,不能用控制端本地 maker。
// 缓存按 (deviceId, agentKind) 隔离 —— 两台机器模型/能力配置可能不同,绝不能串。
// deviceId 省略 = 本机会话,走与改造前逐字节相同的本地路径(零回归)。
type CacheKey = string;
function cacheKey(agentKind: AgentKind, deviceId?: string): CacheKey {
return `${deviceId ?? 'local'}:${agentKind}`;
}
const cache = new Map<CacheKey, AgentCapabilities>();
const inflight = new Map<CacheKey, Promise<AgentCapabilities | null>>();
/** 本地能力刷新代际;使刷新前的在途 IPC 结果无法回写旧快照。 */
let localGen = 0;
/** 已提交的本地快照 revision;失败刷新不会前进,用来区分缺失 tombstone 与未提交。 */
let localSnapshotRevision = 0;
/** 已挂载 hook 的本地能力订阅者;刷新完成后一次性切到新快照,避免中途空白帧。 */
const localListeners = new Set<(agent: AgentKind, caps: AgentCapabilities | null) => void>();
/** 远程能力缓存事件;驱逐时先标 stale,成功 / 失败后再结束这一轮刷新。 */
export type DeviceCapabilitiesEvent =
| { status: 'loading'; retainDisplaySnapshot?: boolean }
| { status: 'ready'; capabilities: AgentCapabilities }
| { status: 'error'; error: string };
/** 已挂载的远程能力订阅者;key 同缓存,provider revision 后可原子换入新快照。 */
const remoteListeners = new Map<CacheKey, Set<(event: DeviceCapabilitiesEvent) => void>>();
/**
* 每被控设备的能力「代际」。`evictDeviceCapabilities` 时自增——在途的 fetchCapabilities 完成
* 回调据此判断「本次请求是否已被驱逐」:被驱逐则**丢弃结果**,既不回写 cache、也不动 inflight
* (evict 已清,且可能已有新一轮 fetch 占了 inflight,误删会破坏新请求)。否则设备下线 / 断链后
* 在途 prefetch 的 .then 会把陈旧 model/effort 重新灌回缓存(重连 / 升级目标端后串旧能力)。
* 本机用 localGen 处理目录热刷新;远端继续按 deviceGen 隔离。
*/
const deviceGen = new Map<string, number>();
function notifyRemoteCapabilities(
deviceId: string,
agentKind: AgentKind,
event: DeviceCapabilitiesEvent,
): void {
for (const listener of remoteListeners.get(cacheKey(agentKind, deviceId)) ?? []) listener(event);
}
/** 订阅某被控端某 agent 的能力快照;只通知当前代际成功提交的完整结果。 */
export function subscribeDeviceCapabilities(
deviceId: string,
agentKind: AgentKind,
listener: (event: DeviceCapabilitiesEvent) => void,
): () => void {
const key = cacheKey(agentKind, deviceId);
const bucket = remoteListeners.get(key) ?? new Set<(event: DeviceCapabilitiesEvent) => void>();
bucket.add(listener);
remoteListeners.set(key, bucket);
return () => {
bucket.delete(listener);
if (bucket.size === 0) remoteListeners.delete(key);
};
}
async function fetchCapabilities(
agentKind: AgentKind,
deviceId?: string,
): Promise<AgentCapabilities | null> {
const key = cacheKey(agentKind, deviceId);
const cached = cache.get(key);
if (cached) return cached;
const ip = inflight.get(key);
if (ip) return ip;
// 捕获发起时的设备代际;回调里若代际已变(被 evict)则认为本次请求作废。
const startGen = deviceId ? (deviceGen.get(deviceId) ?? 0) : localGen;
const startLocalSnapshotRevision = localSnapshotRevision;
const isCurrent = (): boolean =>
deviceId
? (deviceGen.get(deviceId) ?? 0) === startGen
: localGen === startGen && localSnapshotRevision === startLocalSnapshotRevision;
let raw: Promise<AgentCapabilities>;
if (deviceId) {
// 远程:隧道到被控端的 maker:get-capabilities(已在 allowlist)。
const dl = getDeviceLink();
if (!dl) throw new Error('device-link IPC not available');
raw = dl.invoke(deviceId, 'maker:get-capabilities', [agentKind]) as Promise<AgentCapabilities>;
} else {
// 本机:原路径,行为不变。
const api = getMakerApi();
if (!api) throw new Error('maker IPC not available');
raw = api.getCapabilities(agentKind);
}
const p = raw
.then((value) => {
const caps = parseAgentCapabilities(value);
// 在途期间设备被驱逐(下线 / 断链)→ 丢弃结果,不回写 cache、不动 inflight。
if (isCurrent()) {
cache.set(key, caps);
inflight.delete(key);
if (deviceId)
notifyRemoteCapabilities(deviceId, agentKind, { status: 'ready', capabilities: caps });
} else if (!deviceId) {
// 已提交的新快照优先:有值就返回当前 cache,明确删除则以 null 作为 tombstone。
const current = cache.get(key);
if (current) return current;
if (localSnapshotRevision !== startLocalSnapshotRevision) return null;
// 只有刷新代际变化、但最终没有快照提交时,成功的 cache-miss 结果仍然有效。
// 若已有更新请求占住 inflight,则服从更新请求,避免旧结果抢先落缓存。
const newer = inflight.get(key);
if (newer) return newer;
cache.set(key, caps);
return caps;
}
return caps;
})
.catch((e) => {
if (isCurrent()) {
inflight.delete(key);
if (deviceId) {
notifyRemoteCapabilities(deviceId, agentKind, {
status: 'error',
error: e instanceof Error ? e.message : String(e),
});
}
}
throw e;
});
inflight.set(key, p);
return p;
}
export interface UseAgentCapabilitiesResult {
capabilities: AgentCapabilities | null;
loading: boolean;
error: string | null;
}
export function useAgentCapabilities(
agentKind: AgentKind | null | undefined,
deviceId?: string,
): UseAgentCapabilitiesResult {
const selectedKey = agentKind ? cacheKey(agentKind, deviceId) : null;
const initialCapabilities = selectedKey ? cache.get(selectedKey) : undefined;
const [ownerKey, setOwnerKey] = useState<CacheKey | null>(
initialCapabilities ? selectedKey : null,
);
const [capabilities, setCapabilities] = useState<AgentCapabilities | null>(
initialCapabilities ?? null,
);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
if (!agentKind) return undefined;
const key = cacheKey(agentKind, deviceId);
const applyRemoteEvent = (event: DeviceCapabilitiesEvent): void => {
if (event.status === 'loading') {
// 仅同账号配置刷新保留显示快照,账号边界不能展示上一账号的模型。
if (!event.retainDisplaySnapshot) setCapabilities(null);
setOwnerKey(key);
setLoading(true);
setError(null);
return;
}
if (event.status === 'error') {
setOwnerKey(key);
setCapabilities(null);
setLoading(false);
setError(event.error);
return;
}
setOwnerKey(key);
setCapabilities(event.capabilities);
setLoading(false);
setError(null);
};
if (deviceId) return subscribeDeviceCapabilities(deviceId, agentKind, applyRemoteEvent);
const applySnapshot = (caps: AgentCapabilities | null): void => {
setOwnerKey(key);
setCapabilities(caps);
setLoading(false);
setError(null);
};
const onRefresh = (refreshedAgent: AgentKind, caps: AgentCapabilities | null): void => {
if (refreshedAgent !== agentKind) return;
applySnapshot(caps);
};
localListeners.add(onRefresh);
return () => {
localListeners.delete(onRefresh);
};
}, [agentKind, deviceId]);
useEffect(() => {
if (!agentKind) {
setOwnerKey(null);
setCapabilities(null);
setLoading(false);
setError(null);
return;
}
const key = cacheKey(agentKind, deviceId);
const cached = cache.get(key);
if (cached) {
setOwnerKey(key);
setCapabilities(cached);
// 缓存命中 = 数据已就绪,必须把上一目标遗留的 loading / error 一并清掉。
// 漏了会卡死:从「能力还在加载」的设备切到已缓存的设备时走到这里直接 return,
// 后续既没有请求也没有 listener 事件来收尾,loading 就永久停在 true,而创建页的
// send / goal guard 正是看 capabilitiesLoading —— 于是在路由重挂载前一直拒绝创建。
setLoading(false);
setError(null);
return;
}
let cancelled = false;
// cache miss:先清掉上一设备 / 会话的能力,避免 fetch 解析前(失败则永远)UI 残留旧设备的
// 模型 / effort 列表 → 远程会话误选目标端不支持的模型。
setOwnerKey(key);
setCapabilities(null);
setLoading(true);
setError(null);
const remoteGeneration = deviceId ? (deviceGen.get(deviceId) ?? 0) : null;
fetchCapabilities(agentKind, deviceId)
.then((caps) => {
// 远程成功结果只经「当前代际 cache commit → listener」更新,避免 revision 前的
// 旧 Promise 晚到后直接把已刷新的 hook state 覆盖回旧快照。
if (cancelled || deviceId || caps === null) return;
setCapabilities(caps);
})
.catch((e: unknown) => {
if (cancelled) return;
if (deviceId && (deviceGen.get(deviceId) ?? 0) !== remoteGeneration) return;
setError(e instanceof Error ? e.message : String(e));
})
.finally(() => {
if (cancelled) return;
if (deviceId && (deviceGen.get(deviceId) ?? 0) !== remoteGeneration) return;
setLoading(false);
});
return () => {
cancelled = true;
};
}, [agentKind, deviceId]);
const ownsSelection = ownerKey === selectedKey;
return {
capabilities: ownsSelection ? capabilities : null,
loading: selectedKey !== null && (!ownsSelection || loading),
error: ownsSelection ? error : null,
};
}
/**
* 同步读取已缓存的 capabilities (没缓存返回 null)。
* 用于 useMemo / 同步逻辑里需要 capabilities 但又不能起 effect 的场景。
* deviceId 省略 = 本机缓存(行为不变);传 deviceId = 该被控端的缓存。
*/
export function getCachedCapabilities(
agentKind: AgentKind,
deviceId?: string,
): AgentCapabilities | null {
return cache.get(cacheKey(agentKind, deviceId)) ?? null;
}
/**
* device-link:订阅某被控设备时预取其两个 agent 的能力,使首次打开远程会话时
* 模型下拉 / fast / effort 不为空、modelDefinitions 同步层已热。失败 swallow(轮询/打开会话会再取)。
*/
export async function prefetchDeviceCapabilities(deviceId: string): Promise<void> {
await Promise.allSettled(ALL_AGENT_KINDS.map((agent) => fetchCapabilities(agent, deviceId)));
}
/** device-link:被控设备下线 / 断链时驱逐其能力缓存(只清该设备的 key)。 */
export function evictDeviceCapabilities(
deviceId: string,
options?: { retainDisplaySnapshot?: boolean },
): void {
const prefix = `${deviceId}:`;
for (const k of [...cache.keys()]) if (k.startsWith(prefix)) cache.delete(k);
for (const k of [...inflight.keys()]) if (k.startsWith(prefix)) inflight.delete(k);
// 代际自增:作废该设备所有在途 fetch 的回写(防其 .then 把陈旧能力复活回 cache)。
deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
// 已挂载 hook 必须同步知道旧快照已失效;否则 provider 新快照先到时会拿旧 capabilities
// 计算 fallback,并永久覆盖用户原本保存的模型偏好。
for (const agentKind of ALL_AGENT_KINDS) {
notifyRemoteCapabilities(deviceId, agentKind, {
status: 'loading',
...(options?.retainDisplaySnapshot ? { retainDisplaySnapshot: true } : {}),
});
}
}
/** 只清远程能力,本机目录仍由本地刷新代际管理。 */
export function evictAllRemoteCapabilities(): void {
const devices = new Set(deviceGen.keys());
for (const key of [...cache.keys(), ...inflight.keys(), ...remoteListeners.keys()]) {
const deviceId = key.slice(0, key.lastIndexOf(':'));
if (deviceId !== 'local') devices.add(deviceId);
}
for (const deviceId of devices) evictDeviceCapabilities(deviceId);
}
export type LocalCapabilitiesSnapshot = ReadonlyArray<readonly [AgentKind, AgentCapabilities]>;
/** 开始一轮本地 capabilities 刷新,并作废所有更早的本地请求。 */
export function beginLocalCapabilitiesRefresh(): number {
localGen += 1;
for (const agent of ALL_AGENT_KINDS) {
inflight.delete(cacheKey(agent));
}
return localGen;
}
/**
* 读取本地 agent 能力快照;核心 agent 失败向上抛,只有明确的 Pi 未注册结果才不阻断 provider 目录。
*
* Pi 的 CLI 是 best-effort 下载的目录分发,开发机或网络受限时可能暂时缺失。
* 明确未注册时不能让 `maker:get-capabilities('pi')` 的单点失败把 Claude/Codex
* 模型目录整组回滚为空;但临时 IPC、序列化或解析错误必须向上抛,让联合刷新保留
* 上一份完整快照。
*/
export async function loadLocalCapabilitiesSnapshot(): Promise<LocalCapabilitiesSnapshot> {
const api = getMakerApi();
if (!api) throw new Error('maker IPC not available');
const results = await Promise.allSettled(
ALL_AGENT_KINDS.map(async (agent): Promise<readonly [AgentKind, AgentCapabilities] | null> => {
try {
return [agent, await api.getCapabilities(agent)] as const;
} catch (error) {
const message =
error instanceof Error
? error.message
: typeof error === 'object' && error !== null && 'message' in error
? String(error.message)
: String(error);
if (agent !== 'pi' || !message.includes("Agent 'pi' is not registered")) throw error;
log.warn('optional Pi capabilities unavailable; continuing with core agents:', error);
return null;
}
}),
);
const entries = results.map((result) => {
if (result.status === 'rejected') throw result.reason;
return result.value;
});
return entries.filter(
(entry): entry is readonly [AgentKind, AgentCapabilities] => entry !== null,
);
}
export function isLocalCapabilitiesRefreshCurrent(generation: number): boolean {
return localGen === generation;
}
/** 仅提交当前代际的完整能力快照,并在提交后统一通知 mounted hooks。 */
export function commitLocalCapabilitiesSnapshot(
generation: number,
entries: LocalCapabilitiesSnapshot,
): boolean {
if (!isLocalCapabilitiesRefreshCurrent(generation)) return false;
localSnapshotRevision += 1;
const snapshot = new Map(entries);
for (const agent of ALL_AGENT_KINDS) {
const caps = snapshot.get(agent) ?? null;
if (caps) cache.set(cacheKey(agent), caps);
else cache.delete(cacheKey(agent));
for (const listener of localListeners) listener(agent, caps);
}
return true;
}
/**
* Codex auth/discovery 广播后的本地热刷新。旧 cache 在核心 IPC 都成功前继续可读;完成后
* 同时替换 cache 并通知 mounted hooks,避免 provider:list 已更新而 scheduler/selector 仍用旧能力。
*/
export async function refreshLocalCapabilities(): Promise<void> {
const generation = beginLocalCapabilitiesRefresh();
try {
commitLocalCapabilitiesSnapshot(generation, await loadLocalCapabilitiesSnapshot());
} catch (err) {
if (isLocalCapabilitiesRefreshCurrent(generation)) {
log.warn('refreshLocalCapabilities failed:', err);
}
}
}
/**
* 在 app 启动 (preload IPC 就绪后) 调一次, 把两边 agent 的 capabilities 都预拉到 cache。
* 让 modelDefinitions.ts 这种 sync 兼容层立刻有数据。
*/
export async function preloadAllCapabilities(): Promise<void> {
const load = () => Promise.all(ALL_AGENT_KINDS.map((agent) => fetchCapabilities(agent)));
// 防御性重试:EnvCheckGuard 已保证 handler 已注册,这里兜底瞬时 IPC 故障
for (let attempt = 0; attempt < 3; attempt++) {
try {
await load();
return;
} catch (err) {
if (attempt < 2) {
await new Promise((r) => setTimeout(r, 500));
} else {
log.warn('preloadAllCapabilities failed after 3 attempts:', err);
}
}
}
}