Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* Stable, module-neutral API used by remote controllers to discover and operate
* host-owned product resources. Feature modules register providers on the host;
* controllers render the portable collection/resource/action primitives below.
*
* Compatibility rules:
* - fields are additive and consumers must ignore unknown fields;
* - `primitive` and resource `kind` are open strings;
* - every non-core presentation block carries fallbackMarkdown;
* - descriptors are presentation hints, never authorization. The host validates
* every invocation again in the provider that owns the action.
*/
export const REMOTE_RESOURCE_PROTOCOL_VERSION = 1;
export const REMOTE_RESOURCE_MANIFEST_CHANNEL = 'maker:remote-resources:manifest';
export const REMOTE_RESOURCE_LIST_CHANNEL = 'maker:remote-resources:list';
export const REMOTE_RESOURCE_GET_CHANNEL = 'maker:remote-resources:get';
export const REMOTE_RESOURCE_INVOKE_CHANNEL = 'maker:remote-resources:invoke';
export const REMOTE_RESOURCE_CHANGED_CHANNEL = 'maker:remote-resources:changed';
export const REMOTE_RESOURCE_CHANNELS = [
REMOTE_RESOURCE_MANIFEST_CHANNEL,
REMOTE_RESOURCE_LIST_CHANNEL,
REMOTE_RESOURCE_GET_CHANNEL,
REMOTE_RESOURCE_INVOKE_CHANNEL,
] as const;
export interface RemoteLocalizedText {
fallback: string;
translations?: Readonly<Record<string, string>>;
}
export type RemoteText = string | RemoteLocalizedText;
export interface RemoteResourceClientDescriptor {
protocolVersion: number;
/** Portable UI primitives understood by this controller. Open and additive. */
primitives: string[];
/** BCP-47-ish UI locale. It is presentation input, never an authorization signal. */
locale?: string;
}
export interface RemoteResourceRef {
collectionId: string;
kind: string;
id: string;
}
export interface RemoteResourceStatus {
label: RemoteText;
/** Stable visual semantics. Unknown tones must render as neutral. */
tone?: 'neutral' | 'positive' | 'warning' | 'critical' | string;
}
export interface RemoteResourceBadge {
label?: RemoteText;
accessibilityLabel: RemoteText;
tone?: 'neutral' | 'positive' | 'warning' | 'critical' | string;
}
export interface RemoteResourceAvatar {
/** `emoji`, `asset`, `media`, and `text` are the initial portable kinds. Unknown kinds use fallbackText. */
kind: string;
value: string;
fallbackText: string;
color?: string;
}
export interface RemoteResourceDisplay {
title: RemoteText;
subtitle?: RemoteText;
preview?: RemoteText;
/** Ephemeral public generation state. Absent when idle; never a connectivity signal. */
generation?: { phase: string; startedAt: number | null };
/** Optional roster activity; older hosts omit it, older controllers ignore it. */
teammateActivity?: { phase: string };
timestamp?: number;
/** Latest visible reply in host time; controllers keep their own read position. */
lastReplyAt?: number;
avatar?: RemoteResourceAvatar;
status?: RemoteResourceStatus;
badges?: RemoteResourceBadge[];
}
export interface RemoteSessionLinkTarget {
kind: 'session';
sessionId: string;
}
export interface RemoteResourceLinkTarget {
kind: 'resource';
ref: RemoteResourceRef;
}
export type RemoteLinkTarget = RemoteSessionLinkTarget | RemoteResourceLinkTarget;
export interface RemoteResourceLink {
rel: string;
target: RemoteLinkTarget;
label?: RemoteText;
}
export interface RemoteActionField {
id: string;
label: RemoteText;
kind: 'text' | 'multiline' | 'toggle' | 'select' | string;
required?: boolean;
placeholder?: RemoteText;
options?: Array<{ value: string; label: RemoteText }>;
}
export interface RemoteActionDescriptor {
id: string;
label: RemoteText;
/** Presentation only: the host still checks current state at invocation. */
disabled?: boolean;
tone?: 'neutral' | 'primary' | 'destructive' | string;
confirmation?: {
title: RemoteText;
body?: RemoteText;
confirmLabel?: RemoteText;
};
fields?: RemoteActionField[];
}
export interface RemoteResourceBlock {
id: string;
/** Open primitive name. Older controllers render fallbackMarkdown. */
primitive: string;
title?: RemoteText;
fallbackMarkdown: string;
/** session-controls: { input: 'blocked' | 'available', busy: boolean }.
* Controllers may hide their composer while blocked. Hosts must independently
* enforce workspace use; this presentation hint never grants permission.
* search: { query?: string, placeholder?: RemoteText }. Sent only to controllers
* declaring `search`; they re-read the same resource with `RemoteResourceGetRequest.query`.
*/
data?: unknown;
}
export interface RemoteCollectionItem {
ref: RemoteResourceRef;
display: RemoteResourceDisplay;
/** Optional Host-owned plugin chronology. Missing dates remain unknown on older Hosts. */
pluginOrder?: { addedAt?: number; recentIndex?: number };
links: RemoteResourceLink[];
actions?: RemoteActionDescriptor[];
/** Opaque provider revision. Controllers compare it but never interpret it. */
revision: string;
}
export interface RemoteResource extends RemoteCollectionItem {
blocks?: RemoteResourceBlock[];
}
export interface RemoteCollectionDescriptor {
id: string;
resourceKind: string;
title: RemoteText;
/** session:<source> places a resource keyed by Session id beside its composer. */
placement?: string;
icon?: {
name: string;
fallbackText: string;
};
actions?: RemoteActionDescriptor[];
}
export interface RemoteResourceManifestRequest {
client: RemoteResourceClientDescriptor;
}
export interface RemoteResourceManifestResponse {
protocolVersion: number;
collections: RemoteCollectionDescriptor[];
}
export interface RemoteCollectionListRequest {
client: RemoteResourceClientDescriptor;
collectionId: string;
cursor?: string;
limit?: number;
query?: string;
}
export interface RemoteCollectionListResponse {
collectionId: string;
revision: string;
items: RemoteCollectionItem[];
nextCursor?: string;
}
export interface RemoteResourceGetRequest {
client: RemoteResourceClientDescriptor;
ref: RemoteResourceRef;
/**
* Optional filter for a resource that advertised a `search` block. Hosts that do
* not understand it ignore it and return the unfiltered resource; controllers
* only send it after the host declared searchability.
*/
query?: string;
}
export interface RemoteActionInvokeRequest {
client: RemoteResourceClientDescriptor;
collectionId: string;
actionId: string;
resourceRef?: RemoteResourceRef;
input?: Record<string, unknown>;
}
export type RemoteActionEffect =
| { kind: 'refresh-collection'; collectionId: string }
| { kind: 'refresh-resource'; ref: RemoteResourceRef }
| { kind: 'navigate'; target: RemoteLinkTarget }
| { kind: 'toast'; message: RemoteText };
/** Optional opaque reply for an explicitly negotiated resource primitive. */
export interface RemoteActionInvokeResponse {
result?: unknown;
effects: RemoteActionEffect[];
}
export interface RemoteResourceChangedPayload {
collectionId: string;
resourceRefs?: RemoteResourceRef[];
revision?: string;
}
const MAX_ID_CHARS = 160;
const MAX_RESOURCE_ID_CHARS = 256;
const MAX_CURSOR_CHARS = 1_024;
const MAX_QUERY_CHARS = 1_000;
const MAX_LOCALE_CHARS = 64;
const MAX_PRIMITIVES = 128;
const MAX_ACTION_INPUT_BYTES = 64 * 1_024;
function recordOf(value: unknown): Record<string, unknown> | null {
return value && typeof value === 'object' && !Array.isArray(value)
? value as Record<string, unknown>
: null;
}
function boundedText(value: unknown, max: number): string | null {
return typeof value === 'string' && value.length > 0 && value.length <= max ? value : null;
}
/** Dependency-free UTF-8 byte count; this package also runs in React Native. */
function utf8ByteLength(value: string): number {
let bytes = 0;
for (const char of value) {
const codePoint = char.codePointAt(0) ?? 0;
bytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
}
return bytes;
}
export function parseRemoteResourceClientDescriptor(
value: unknown,
): RemoteResourceClientDescriptor | null {
const record = recordOf(value);
if (!record) return null;
const protocolVersion = record.protocolVersion;
const primitives = record.primitives;
if (!Number.isInteger(protocolVersion) || (protocolVersion as number) < 1) return null;
if (!Array.isArray(primitives) || primitives.length > MAX_PRIMITIVES) return null;
const normalizedPrimitives: string[] = [];
for (const primitive of primitives) {
const normalized = boundedText(primitive, MAX_ID_CHARS);
if (!normalized) return null;
if (!normalizedPrimitives.includes(normalized)) normalizedPrimitives.push(normalized);
}
const locale = record.locale === undefined
? undefined
: boundedText(record.locale, MAX_LOCALE_CHARS);
if (record.locale !== undefined && !locale) return null;
return {
protocolVersion: protocolVersion as number,
primitives: normalizedPrimitives,
...(locale ? { locale } : {}),
};
}
export function parseRemoteResourceRef(value: unknown): RemoteResourceRef | null {
const record = recordOf(value);
if (!record) return null;
const collectionId = boundedText(record.collectionId, MAX_ID_CHARS);
const kind = boundedText(record.kind, MAX_ID_CHARS);
const id = boundedText(record.id, MAX_RESOURCE_ID_CHARS);
return collectionId && kind && id ? { collectionId, kind, id } : null;
}
export function parseRemoteResourceManifestRequest(
value: unknown,
): RemoteResourceManifestRequest | null {
const record = recordOf(value);
const client = parseRemoteResourceClientDescriptor(record?.client);
return client ? { client } : null;
}
export function parseRemoteCollectionListRequest(
value: unknown,
): RemoteCollectionListRequest | null {
const record = recordOf(value);
if (!record) return null;
const client = parseRemoteResourceClientDescriptor(record.client);
const collectionId = boundedText(record.collectionId, MAX_ID_CHARS);
if (!client || !collectionId) return null;
const cursor = record.cursor === undefined ? undefined : boundedText(record.cursor, MAX_CURSOR_CHARS);
const query = record.query === undefined ? undefined : boundedText(record.query, MAX_QUERY_CHARS);
const limit = record.limit === undefined
? undefined
: Number.isInteger(record.limit) && (record.limit as number) > 0 && (record.limit as number) <= 200
? record.limit as number
: null;
if ((record.cursor !== undefined && !cursor) || (record.query !== undefined && !query) || limit === null) {
return null;
}
return {
client,
collectionId,
...(cursor ? { cursor } : {}),
...(query ? { query } : {}),
...(limit ? { limit } : {}),
};
}
export function parseRemoteResourceChangedPayload(
value: unknown,
): RemoteResourceChangedPayload | null {
const record = recordOf(value);
if (!record) return null;
const collectionId = boundedText(record.collectionId, MAX_ID_CHARS);
if (!collectionId) return null;
let resourceRefs: RemoteResourceRef[] | undefined;
if (record.resourceRefs !== undefined) {
if (!Array.isArray(record.resourceRefs) || record.resourceRefs.length > 256) return null;
resourceRefs = [];
for (const candidate of record.resourceRefs) {
const ref = parseRemoteResourceRef(candidate);
if (!ref || ref.collectionId !== collectionId) return null;
resourceRefs.push(ref);
}
}
const revision = record.revision === undefined
? undefined
: boundedText(record.revision, MAX_CURSOR_CHARS);
if (record.revision !== undefined && revision === null) return null;
return {
collectionId,
...(resourceRefs ? { resourceRefs } : {}),
...(revision ? { revision } : {}),
};
}
export function parseRemoteResourceGetRequest(value: unknown): RemoteResourceGetRequest | null {
const record = recordOf(value);
if (!record) return null;
const client = parseRemoteResourceClientDescriptor(record.client);
const ref = parseRemoteResourceRef(record.ref);
if (!client || !ref) return null;
// Same bound as collection list queries; an empty query means "no filter".
if (record.query === undefined || record.query === '') return { client, ref };
const query = boundedText(record.query, MAX_QUERY_CHARS);
return query ? { client, ref, query } : null;
}
export function parseRemoteActionInvokeRequest(value: unknown): RemoteActionInvokeRequest | null {
const record = recordOf(value);
if (!record) return null;
const client = parseRemoteResourceClientDescriptor(record.client);
const collectionId = boundedText(record.collectionId, MAX_ID_CHARS);
const actionId = boundedText(record.actionId, MAX_ID_CHARS);
if (!client || !collectionId || !actionId) return null;
const resourceRef = record.resourceRef === undefined
? undefined
: parseRemoteResourceRef(record.resourceRef);
if (record.resourceRef !== undefined && !resourceRef) return null;
const input = record.input === undefined ? undefined : recordOf(record.input);
if (record.input !== undefined && !input) return null;
if (input) {
try {
if (utf8ByteLength(JSON.stringify(input)) > MAX_ACTION_INPUT_BYTES) return null;
} catch {
return null;
}
}
return {
client,
collectionId,
actionId,
...(resourceRef ? { resourceRef } : {}),
...(input ? { input } : {}),
};
}
/** Resolve host-owned copy without requiring a mobile release for new labels. */
export function resolveRemoteText(value: RemoteText, locale?: string): string {
if (typeof value === 'string') return value;
if (!value || typeof value !== 'object' || typeof value.fallback !== 'string') return '';
if (!locale || !value.translations || typeof value.translations !== 'object') return value.fallback;
const exact = value.translations[locale];
if (typeof exact === 'string' && exact) return exact;
const language = locale.split('-')[0];
const translated = value.translations[language];
return typeof translated === 'string' && translated ? translated : value.fallback;
}