Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { deviceDisplayName } from '@/device-link/deviceName';
import {
REMOTE_RESOURCE_GET_CHANNEL,
REMOTE_RESOURCE_INVOKE_CHANNEL,
REMOTE_RESOURCE_LIST_CHANNEL,
REMOTE_RESOURCE_MANIFEST_CHANNEL,
REMOTE_RESOURCE_PROTOCOL_VERSION,
parseRemoteResourceRef,
resolveRemoteText,
type RemoteActionInvokeResponse,
type RemoteCollectionDescriptor,
type RemoteCollectionItem,
type RemoteCollectionListResponse,
type RemoteResourceAvatar,
type RemoteResourceDisplay,
type RemoteResourceLink,
type RemoteResourceClientDescriptor,
type RemoteResource,
type RemoteResourceManifestResponse,
type RemoteResourceRef,
type RemoteResourceStatus,
type RemoteText,
type RemoteActionDescriptor,
type RemoteResourceBlock,
} from '@cindy/device-link';
import { BOT_GROUP_CHAT_PRIMITIVE, type BotGroupMemberView } from '@cindy/maker-shared/botGroupChat';
import { normalizeRemoteActions, normalizeRemoteBlocks } from './remoteResourceContent';
import type { RemoteInvoke } from './mobileMakerTransport';
export const MOBILE_REMOTE_RESOURCE_PRIMITIVES = [
'status',
'session-link',
'session-controls',
] as const;
/**
* Primitives whose whole block data is kept for a dedicated screen that asked for them
* (`getRemoteResource(..., supportedPrimitives)`); ordinary resource views never get it.
* The screen still validates that data before using it.
*/
const RICH_REMOTE_RESOURCE_PRIMITIVES: readonly string[] = [
'form',
'routine-list',
'routine-detail',
BOT_GROUP_CHAT_PRIMITIVE,
'plugin-capabilities',
'plugin-card-actions',
'plugin-card-forms',
'mail-message',
'teammate-todos',
];
/** Routines remain a desktop feature; other portable collections stay available. */
export function isMobileRemoteCollectionSupported(collectionId: string): boolean {
return collectionId !== 'routines';
}
function assertMobileRemoteCollectionSupported(collectionId: string): void {
if (!isMobileRemoteCollectionSupported(collectionId)) {
throw new Error('Unsupported mobile resource collection');
}
}
export interface RemoteResourceHostTarget {
deviceId: string;
deviceName: string;
}
/** Availability applies to discovery only; offline entries retain their cached projection. */
export interface RemoteResourceDiscoveryTarget extends RemoteResourceHostTarget {
offline?: boolean;
}
export interface RemoteHomeCollection {
id: string;
title: string;
resourceKind: string;
placement?: string;
iconName?: string;
targets: RemoteResourceHostTarget[];
}
/** Offline hosts keep an already discovered entry; revoked/disabled hosts do not. */
export function remoteResourceDiscoveryTargets(
devices: readonly { canOpen: boolean; state: string; deviceId: string; name: string }[],
previous: readonly RemoteHomeCollection[],
): RemoteResourceDiscoveryTarget[] {
const known = new Set(previous.flatMap((collection) => collection.targets.map((host) => host.deviceId)));
return devices
.filter((device) => device.canOpen || (device.state === 'offline' && known.has(device.deviceId)))
.map((device) => ({ deviceId: device.deviceId, deviceName: deviceDisplayName(device.deviceId, device.name, devices),
...(!device.canOpen ? { offline: true } : {}),
}));
}
function clientDescriptor(locale?: string): RemoteResourceClientDescriptor {
return {
protocolVersion: REMOTE_RESOURCE_PROTOCOL_VERSION,
primitives: [...MOBILE_REMOTE_RESOURCE_PRIMITIVES],
...(locale ? { locale } : {}),
};
}
function recordOf(value: unknown): Record<string, unknown> | null {
return value && typeof value === 'object' && !Array.isArray(value)
? value as Record<string, unknown>
: null;
}
const MAX_REMOTE_ID_CHARS = 160;
const MAX_REMOTE_TEXT_CHARS = 20_000;
const MAX_REMOTE_TRANSLATIONS = 32;
function boundedString(value: unknown, max: number, allowEmpty = false): string | null {
return typeof value === 'string'
&& value.length <= max
&& (allowEmpty || value.length > 0)
? value
: null;
}
function normalizeRemoteText(value: unknown, max = MAX_REMOTE_TEXT_CHARS): RemoteText | null {
const direct = boundedString(value, max);
if (direct) return direct;
const record = recordOf(value);
const fallback = boundedString(record?.fallback, max);
if (!record || !fallback) return null;
const translationsRecord = recordOf(record.translations);
if (!translationsRecord) return { fallback };
const translations: Record<string, string> = {};
for (const [locale, text] of Object.entries(translationsRecord)) {
if (Object.keys(translations).length >= MAX_REMOTE_TRANSLATIONS) break;
const normalizedLocale = boundedString(locale, 64);
const normalizedText = boundedString(text, max);
if (normalizedLocale && normalizedText) translations[normalizedLocale] = normalizedText;
}
return Object.keys(translations).length > 0 ? { fallback, translations } : { fallback };
}
function normalizeRemoteRef(value: unknown): RemoteResourceRef | null {
return parseRemoteResourceRef(value);
}
function normalizeRemoteStatus(value: unknown): RemoteResourceStatus | null {
const record = recordOf(value);
const label = normalizeRemoteText(record?.label, 512);
if (!record || !label) return null;
const tone = boundedString(record.tone, 64);
return { label, ...(tone ? { tone } : {}) };
}
function normalizeRemoteAvatar(value: unknown): RemoteResourceAvatar | null {
const record = recordOf(value);
const kind = boundedString(record?.kind, 64);
const avatarValue = boundedString(record?.value, 256_000, true);
const fallbackText = boundedString(record?.fallbackText, 64, true);
if (!record || !kind || avatarValue === null || fallbackText === null) return null;
const color = boundedString(record.color, 64);
return {
kind,
value: avatarValue,
fallbackText,
...(color ? { color } : {}),
};
}
function normalizeRemoteTimestamp(value: unknown): number | undefined {
if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
return Number.isFinite(new Date(value).getTime()) ? value : undefined;
}
function normalizeRemoteDisplay(value: unknown): RemoteResourceDisplay | null {
const record = recordOf(value);
const title = normalizeRemoteText(record?.title, 512);
if (!record || !title) return null;
const subtitle = normalizeRemoteText(record.subtitle, 4_096);
const preview = normalizeRemoteText(record.preview, 4_096);
const timestamp = normalizeRemoteTimestamp(record.timestamp);
const avatar = normalizeRemoteAvatar(record.avatar);
const status = normalizeRemoteStatus(record.status);
const generation = recordOf(record.generation);
const generationPhase = boundedString(generation?.phase, 80);
const generationStartedAt = normalizeRemoteTimestamp(generation?.startedAt);
return {
title,
...(subtitle ? { subtitle } : {}),
...(preview ? { preview } : {}),
...(boundedString(recordOf(record.teammateActivity)?.phase, 80)
? { teammateActivity: { phase: boundedString(recordOf(record.teammateActivity)?.phase, 80)! } } : {}),
...(generationPhase ? { generation: { phase: generationPhase, startedAt: generationStartedAt ?? null } } : {}),
...(timestamp !== undefined ? { timestamp } : {}),
...(normalizeRemoteTimestamp(record.lastReplyAt) !== undefined ? { lastReplyAt: record.lastReplyAt as number } : {}),
...(avatar ? { avatar } : {}),
...(status ? { status } : {}),
...(Array.isArray(record.badges) ? { badges: record.badges.slice(0, 8).flatMap(value => {
const badge = recordOf(value);
const accessibilityLabel = normalizeRemoteText(badge?.accessibilityLabel, 512);
return accessibilityLabel ? [{ accessibilityLabel, tone: boundedString(badge?.tone, 64) ?? 'neutral' }] : [];
}) } : {}),
};
}
function normalizeRemoteLink(value: unknown): RemoteResourceLink | null {
const record = recordOf(value);
const rel = boundedString(record?.rel, MAX_REMOTE_ID_CHARS);
const target = recordOf(record?.target);
if (!record || !rel || !target) return null;
let normalizedTarget: RemoteResourceLink['target'] | null = null;
if (target.kind === 'session') {
const sessionId = boundedString(target.sessionId, MAX_REMOTE_ID_CHARS);
if (sessionId) normalizedTarget = { kind: 'session', sessionId };
} else if (target.kind === 'resource') {
const ref = normalizeRemoteRef(target.ref);
if (ref) normalizedTarget = { kind: 'resource', ref };
}
if (!normalizedTarget) return null;
const label = normalizeRemoteText(record.label, 512);
return { rel, target: normalizedTarget, ...(label ? { label } : {}) };
}
function validDescriptor(value: unknown): RemoteCollectionDescriptor | null {
const record = recordOf(value);
if (!record) return null;
const id = boundedString(record.id, MAX_REMOTE_ID_CHARS);
const resourceKind = boundedString(record.resourceKind, MAX_REMOTE_ID_CHARS);
const title = normalizeRemoteText(record.title, 512);
if (!id || !resourceKind || !title) return null;
const placement = boundedString(record.placement, MAX_REMOTE_ID_CHARS);
const iconRecord = recordOf(record.icon);
const iconName = boundedString(iconRecord?.name, MAX_REMOTE_ID_CHARS);
const iconFallbackText = boundedString(iconRecord?.fallbackText, 64, true);
return {
id,
resourceKind,
title,
...(record.actions !== undefined ? { actions: normalizeRemoteActions(record.actions) } : {}),
...(placement ? { placement } : {}),
...(iconName && iconFallbackText !== null
? { icon: { name: iconName, fallbackText: iconFallbackText } }
: {}),
};
}
function normalizeManifest(value: unknown): RemoteResourceManifestResponse | null {
const record = recordOf(value);
if (!record || !Array.isArray(record.collections)) return null;
const collections = record.collections.flatMap((item) => {
const descriptor = validDescriptor(item);
return descriptor && isMobileRemoteCollectionSupported(descriptor.id) ? [descriptor] : [];
});
const protocolVersion = typeof record.protocolVersion === 'number'
? record.protocolVersion
: REMOTE_RESOURCE_PROTOCOL_VERSION;
return { protocolVersion, collections };
}
function errorCode(error: unknown): string {
if (error && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'string') {
return (error as { code: string }).code;
}
return '';
}
export function isRemoteResourcesUnsupported(error: unknown): boolean {
const code = errorCode(error);
if (code === 'CHANNEL_NOT_ALLOWED' || code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED') return true;
const message = error instanceof Error ? error.message : String(error);
return message.includes('CHANNEL_NOT_ALLOWED');
}
export async function loadRemoteResourceManifest(
invoke: RemoteInvoke,
target: RemoteResourceHostTarget,
locale?: string,
): Promise<RemoteResourceManifestResponse | null> {
try {
const raw = await invoke(target.deviceId, REMOTE_RESOURCE_MANIFEST_CHANNEL, [{
client: clientDescriptor(locale),
}]);
return normalizeManifest(raw);
} catch (error) {
if (isRemoteResourcesUnsupported(error)) return null;
throw error;
}
}
/**
* Merge the same host-advertised collection across computers. The mobile shell
* uses placement and portable display primitives after applying mobile availability.
*/
export async function discoverRemoteHomeCollections(
invoke: RemoteInvoke,
targets: readonly RemoteResourceDiscoveryTarget[],
locale?: string,
previous: readonly RemoteHomeCollection[] = [],
onProgress?: (collections: RemoteHomeCollection[]) => void,
): Promise<RemoteHomeCollection[]> {
const cachedManifest = (target: RemoteResourceHostTarget): RemoteResourceManifestResponse => ({
protocolVersion: REMOTE_RESOURCE_PROTOCOL_VERSION,
collections: previous.filter((collection) => collection.targets.some(
(candidate) => candidate.deviceId === target.deviceId,
)).map((collection) => ({
id: collection.id,
resourceKind: collection.resourceKind,
title: collection.title,
...(collection.placement ? { placement: collection.placement } : {}),
...(collection.iconName ? { icon: { name: collection.iconName, fallbackText: '' } } : {}),
})),
});
const merge = (discovered: { target: RemoteResourceHostTarget; manifest: RemoteResourceManifestResponse | null }[]) => {
const byId = new Map<string, RemoteHomeCollection>();
for (const { target, manifest } of discovered) {
for (const collection of manifest?.collections ?? []) {
if (collection.placement !== 'home-scope' || !isMobileRemoteCollectionSupported(collection.id)) continue;
const existing = byId.get(collection.id);
if (existing && existing.resourceKind === collection.resourceKind) {
existing.targets.push(target);
continue;
}
if (existing) continue;
byId.set(collection.id, {
id: collection.id,
title: resolveRemoteText(collection.title, locale),
resourceKind: collection.resourceKind,
placement: collection.placement,
iconName: collection.icon?.name,
targets: [target],
});
}
}
return [...byId.values()];
};
const discovered = targets.map(({ offline: _offline, ...target }) => ({ target, manifest: cachedManifest(target) as RemoteResourceManifestResponse | null }));
const settled = await Promise.allSettled(targets.map(async ({ offline, ...target }, index) => {
const manifest = offline ? cachedManifest(target) : await loadRemoteResourceManifest(invoke, target, locale);
discovered[index] = { target, manifest };
onProgress?.(merge(discovered));
return { target, manifest };
}));
const hasManifestReply = settled.some((result, index) => result.status === 'fulfilled'
&& result.value.manifest !== null && !targets[index].offline);
if (targets.length > 0 && !hasManifestReply && !discovered.some(entry => entry.manifest?.collections.length)) {
const failure = settled.find((result) => result.status === 'rejected');
if (failure && failure.status === 'rejected') throw failure.reason;
}
return merge(discovered);
}
export async function invokeRemoteResourceAction(
invoke: RemoteInvoke,
target: RemoteResourceHostTarget,
request: {
collectionId: string;
actionId: string;
resourceRef?: RemoteResourceRef;
input?: Record<string, unknown>;
},
locale?: string,
): Promise<RemoteActionInvokeResponse> {
assertMobileRemoteCollectionSupported(request.collectionId);
if (request.resourceRef) assertMobileRemoteCollectionSupported(request.resourceRef.collectionId);
return invoke<RemoteActionInvokeResponse>(target.deviceId, REMOTE_RESOURCE_INVOKE_CHANNEL, [{
client: clientDescriptor(locale),
...request,
}]);
}
export async function getRemoteResource(
invoke: RemoteInvoke,
target: RemoteResourceHostTarget,
ref: RemoteResourceRef,
locale?: string,
supportedPrimitives: readonly string[] = [],
query?: string,
): Promise<RemoteResource> {
assertMobileRemoteCollectionSupported(ref.collectionId);
const raw = await invoke<unknown>(target.deviceId, REMOTE_RESOURCE_GET_CHANNEL, [{
client: { ...clientDescriptor(locale), primitives: [...MOBILE_REMOTE_RESOURCE_PRIMITIVES, ...supportedPrimitives] },
ref,
...(query ? {query} : {}),
}]);
const normalized = normalizeRemoteCollectionItem(raw, ref.collectionId);
if (!normalized || normalized.ref.kind !== ref.kind || normalized.ref.id !== ref.id) {
throw new Error('invalid remote resource response');
}
const source = recordOf(raw);
// Rich forms are consumed only by the dedicated editor, never ordinary resource views.
if (supportedPrimitives.some(primitive => RICH_REMOTE_RESOURCE_PRIMITIVES.includes(primitive))) return {
...normalized, actions: normalizeRemoteActions(source?.actions), blocks: normalizeRemoteBlocks(source?.blocks),
};
const actions: RemoteActionDescriptor[] = Array.isArray(source?.actions)
? source.actions.slice(0, 16).flatMap((value) => {
const entry = recordOf(value);
const id = boundedString(entry?.id, MAX_REMOTE_ID_CHARS);
const label = normalizeRemoteText(entry?.label, 512);
// Forms remain unsupported; a malformed confirmation must never become an unconfirmed action.
if (!entry || !id || !label || entry.fields) return [];
let confirmation: RemoteActionDescriptor['confirmation'];
if (entry.confirmation !== undefined) {
const raw = recordOf(entry.confirmation);
const title = normalizeRemoteText(raw?.title, 512);
const body = raw?.body === undefined ? undefined : normalizeRemoteText(raw.body, 8192);
const confirmLabel = raw?.confirmLabel === undefined ? undefined : normalizeRemoteText(raw.confirmLabel, 512);
if (!title || body === null || confirmLabel === null) return [];
confirmation = { title, ...(body ? { body } : {}), ...(confirmLabel ? { confirmLabel } : {}) };
}
return [{ id, label, disabled: entry.disabled !== undefined && entry.disabled !== false,
...(entry.tone === 'destructive' ? { tone: 'destructive' } : {}),
...(confirmation ? { confirmation } : {}),
}];
}) : [];
const blocks: RemoteResourceBlock[] | undefined = Array.isArray(source?.blocks) ? source.blocks.slice(0, 256).flatMap<RemoteResourceBlock>((rawBlock) => {
const block = recordOf(rawBlock);
const id = boundedString(block?.id, 256);
const primitive = boundedString(block?.primitive, 64);
const fallbackMarkdown = typeof block?.fallbackMarkdown === 'string' ? block.fallbackMarkdown : null;
if (!id || !primitive || fallbackMarkdown === null || fallbackMarkdown.length > 131072) return [];
// Only the inert media URL primitive is needed here. Never copy arbitrary host data.
const data = recordOf(block?.data);
if (ref.kind === 'bot' && id === 'invitation' && primitive === 'status'
&& typeof data?.stage === 'string' && ['profile', 'skills', 'avatar', 'welcome', 'ready', 'failed'].includes(data.stage))
return [{ id, primitive, fallbackMarkdown, data: { stage: data.stage } }];
if (primitive === 'session-controls') return [{ id, primitive, fallbackMarkdown,
data: { input: data?.input === 'available' ? 'available' : 'blocked', busy: data?.busy === true } }];
const inlineIcon = ref.collectionId === 'plugin-identities' && id === 'icon' && primitive === 'image';
const url = boundedString(data?.url, inlineIcon ? 256_000 : 4096);
return [{ id, primitive, fallbackMarkdown, ...(url ? { data: { url } } : {}) }];
}) : undefined;
return { ...normalized, ...(actions.length ? { actions } : {}), ...(blocks ? { blocks } : {}) };
}
function normalizeRemoteCollectionItem(
candidate: unknown,
collectionId: string,
): RemoteCollectionItem | null {
const item = recordOf(candidate);
const ref = normalizeRemoteRef(item?.ref);
const display = normalizeRemoteDisplay(item?.display);
const revision = boundedString(item?.revision, 1_024);
if (!item || !ref || ref.collectionId !== collectionId || !display || !revision) return null;
// A teammate row carries a link per open task it follows (the desktop sends at most 200).
const links = Array.isArray(item.links)
? item.links.slice(0, 256).flatMap((link) => {
const normalized = normalizeRemoteLink(link);
return normalized ? [normalized] : [];
})
: [];
const rawOrder = collectionId === 'plugins' ? recordOf(item.pluginOrder) : null;
const addedAt = rawOrder?.addedAt;
const recentIndex = rawOrder?.recentIndex;
const pluginOrder = rawOrder ? {
...(typeof addedAt === 'number' && Number.isSafeInteger(addedAt) && addedAt > 0 ? { addedAt } : {}),
...(typeof recentIndex === 'number' && Number.isSafeInteger(recentIndex) && recentIndex >= 0 && recentIndex < 100 ? { recentIndex } : {}),
} : undefined;
return { ref, display, links, revision,
...(pluginOrder && Object.keys(pluginOrder).length ? { pluginOrder } : {}),
...(collectionId === 'plugins' ? { actions: normalizeRemoteActions(item.actions) } : {}),
};
}
export function normalizeRemoteCollectionItems(
value: unknown,
collectionId: string,
): RemoteCollectionItem[] {
if (!isMobileRemoteCollectionSupported(collectionId)) return [];
const record = recordOf(value);
if (!record || !Array.isArray(record.items)) return [];
return record.items.slice(0, 200).flatMap((candidate) => {
const item = normalizeRemoteCollectionItem(candidate, collectionId);
return item ? [item] : [];
});
}
export interface HostedRemoteCollectionItem {
key: string;
host: RemoteResourceHostTarget;
item: RemoteCollectionItem;
/** Local direct Chat Server projection; never changes the device-link wire display. */
lastReplySequence?: string;
chatUnread?: { count: number; mentioned: boolean; threadCount: number; threadMentioned: boolean };
/** Authorized server identities for direct group rows; display only, never cached as permissions. */
groupMembers?: readonly Pick<BotGroupMemberView, 'botId' | 'name' | 'avatar' | 'avatarUrl' | 'avatarColor'>[];
}
/** Replace successful host shards while retaining stale rows for transiently failed hosts. */
export function mergeRemoteCollectionHostShards(
current: readonly HostedRemoteCollectionItem[],
next: readonly HostedRemoteCollectionItem[],
successfulDeviceIds: ReadonlySet<string>,
targets: readonly RemoteResourceHostTarget[],
): HostedRemoteCollectionItem[] {
const sourceFor = (deviceId: string) => (successfulDeviceIds.has(deviceId) ? next : current)
.filter((entry) => entry.host.deviceId === deviceId);
return targets.flatMap((target) => sourceFor(target.deviceId));
}
export async function listRemoteCollection(
invoke: RemoteInvoke,
target: RemoteResourceHostTarget,
collectionId: string,
locale?: string,
query?: string,
): Promise<RemoteCollectionListResponse> {
assertMobileRemoteCollectionSupported(collectionId);
return invoke<RemoteCollectionListResponse>(target.deviceId, REMOTE_RESOURCE_LIST_CHANNEL, [{
client: clientDescriptor(locale),
collectionId,
limit: 200,
...(query ? { query } : {}),
}]);
}
const MAX_TARGETS = 32;
const MAX_TARGET_FIELD_CHARS = 256;
export function serializeRemoteResourceTargets(
targets: readonly RemoteResourceHostTarget[],
): string {
return JSON.stringify(targets.slice(0, MAX_TARGETS).map((target) => ({
deviceId: target.deviceId.slice(0, MAX_TARGET_FIELD_CHARS),
deviceName: target.deviceName.slice(0, MAX_TARGET_FIELD_CHARS),
})));
}
export function parseRemoteResourceTargets(value: unknown): RemoteResourceHostTarget[] {
const raw = Array.isArray(value) ? value[0] : value;
if (typeof raw !== 'string' || raw.length > 32_000) return [];
try {
const parsed = JSON.parse(raw);
if (!Array.isArray(parsed)) return [];
return parsed.slice(0, MAX_TARGETS).flatMap((item) => {
const record = recordOf(item);
if (!record) return [];
const deviceId = typeof record.deviceId === 'string' ? record.deviceId : '';
const deviceName = typeof record.deviceName === 'string' ? record.deviceName : '';
if (
!deviceId
|| deviceId.length > MAX_TARGET_FIELD_CHARS
|| deviceName.length > MAX_TARGET_FIELD_CHARS
) {
return [];
}
return [{ deviceId, deviceName: deviceDisplayName(deviceId, deviceName) }];
});
} catch {
return [];
}
}