@heybox/hb-sdk-protocol 0.8.1-alpha.3 → 0.8.1-alpha.7

package/src/capabilities.ts

@@ -1,4 +1,29 @@
 import type {
+  CompanionCancelPreparationPayload,
+  CompanionCancelPreparationResult,
+  CompanionGetActiveSessionPayload,
+  CompanionGetActiveSessionResult,
+  CompanionGetInfoPayload,
+  CompanionGetInfoResult,
+  CompanionGetPreparationStatusPayload,
+  CompanionGetPreparationStatusResult,
+  CompanionLaunchPayload,
+  CompanionLaunchResult,
+  CompanionOpenAttachmentPayload,
+  CompanionOpenAttachmentResult,
+  CompanionPreparePayload,
+  CompanionPrepareProgress,
+  CompanionPrepareResult,
+  CompanionSessionAckOutputPayload,
+  CompanionSessionAckOutputResult,
+  CompanionSessionCloseStdinPayload,
+  CompanionSessionCloseStdinResult,
+  CompanionSessionTerminatePayload,
+  CompanionSessionTerminateResult,
+  CompanionSessionWritePayload,
+  CompanionSessionWriteResult,
+  CompanionShowNotificationPayload,
+  CompanionShowNotificationResult,
   ClosePayload,
   CloseResult,
   CopyLinkPayload,
@@ -11,6 +36,7 @@ import type {
   DirectoryListResult,
   DirectoryRemovePayload,
   DirectoryRemoveResult,
+  DownloadProgressPayload,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -122,6 +148,18 @@ export const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList' as
 export const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry' as const;
 export const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry' as const;
 export const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo' as const;
+export const COMPANION_GET_INFO_METHOD = 'companion.getInfo' as const;
+export const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus' as const;
+export const COMPANION_PREPARE_METHOD = 'companion.prepare' as const;
+export const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation' as const;
+export const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession' as const;
+export const COMPANION_LAUNCH_METHOD = 'companion.launch' as const;
+export const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write' as const;
+export const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin' as const;
+export const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate' as const;
+export const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput' as const;
+export const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment' as const;
+export const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification' as const;
 
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
@@ -153,6 +191,19 @@ export type MiniProgramCloudMethod =
   | typeof CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD
   | typeof CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD
   | typeof CLOUD_LEADERBOARD_GET_INFO_METHOD;
+export type MiniProgramCompanionMethod =
+  | typeof COMPANION_GET_INFO_METHOD
+  | typeof COMPANION_GET_PREPARATION_STATUS_METHOD
+  | typeof COMPANION_PREPARE_METHOD
+  | typeof COMPANION_CANCEL_PREPARATION_METHOD
+  | typeof COMPANION_GET_ACTIVE_SESSION_METHOD
+  | typeof COMPANION_LAUNCH_METHOD
+  | typeof COMPANION_SESSION_WRITE_METHOD
+  | typeof COMPANION_SESSION_CLOSE_STDIN_METHOD
+  | typeof COMPANION_SESSION_TERMINATE_METHOD
+  | typeof COMPANION_SESSION_ACK_OUTPUT_METHOD
+  | typeof COMPANION_OPEN_ATTACHMENT_METHOD
+  | typeof COMPANION_SHOW_NOTIFICATION_METHOD;
 export type MiniProgramBridgeMethod =
   | MiniProgramAuthMethod
   | MiniProgramUserMethod
@@ -166,7 +217,8 @@ export type MiniProgramBridgeMethod =
   | MiniProgramUiMethod
   | MiniProgramDeviceMethod
   | MiniProgramNavigationMethod
-  | MiniProgramCloudMethod;
+  | MiniProgramCloudMethod
+  | MiniProgramCompanionMethod;
 export type MiniProgramCapabilityModule =
   | 'auth'
   | 'user'
@@ -180,7 +232,8 @@ export type MiniProgramCapabilityModule =
   | 'ui'
   | 'device'
   | 'navigation'
-  | 'cloud';
+  | 'cloud'
+  | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 
 export interface MiniProgramCapabilityDefinition {
@@ -437,6 +490,26 @@ export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'low',
   },
+  ...[
+    COMPANION_GET_INFO_METHOD,
+    COMPANION_GET_PREPARATION_STATUS_METHOD,
+    COMPANION_PREPARE_METHOD,
+    COMPANION_CANCEL_PREPARATION_METHOD,
+    COMPANION_GET_ACTIVE_SESSION_METHOD,
+    COMPANION_LAUNCH_METHOD,
+    COMPANION_SESSION_WRITE_METHOD,
+    COMPANION_SESSION_CLOSE_STDIN_METHOD,
+    COMPANION_SESSION_TERMINATE_METHOD,
+    COMPANION_SESSION_ACK_OUTPUT_METHOD,
+    COMPANION_OPEN_ATTACHMENT_METHOD,
+    COMPANION_SHOW_NOTIFICATION_METHOD,
+  ].map((method) => ({
+    method,
+    module: 'companion' as const,
+    capability: method,
+    requirement: { kind: 'all' as const, permissions: ['companion' as const] },
+    risk: 'high' as const,
+  })),
 ] as const satisfies readonly MiniProgramCapabilityDefinition[];
 
 export interface MiniProgramCapabilityPayloadMap {
@@ -481,6 +554,18 @@ export interface MiniProgramCapabilityPayloadMap {
   [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryPayload | undefined;
   [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryPayload | undefined;
   [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoPayload | undefined;
+  [COMPANION_GET_INFO_METHOD]: CompanionGetInfoPayload;
+  [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusPayload;
+  [COMPANION_PREPARE_METHOD]: CompanionPreparePayload;
+  [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationPayload;
+  [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionPayload;
+  [COMPANION_LAUNCH_METHOD]: CompanionLaunchPayload;
+  [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWritePayload;
+  [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinPayload;
+  [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminatePayload;
+  [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputPayload;
+  [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentPayload;
+  [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationPayload;
 }
 
 export interface MiniProgramCapabilityResultMap {
@@ -525,7 +610,27 @@ export interface MiniProgramCapabilityResultMap {
   [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
   [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
   [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
+  [COMPANION_GET_INFO_METHOD]: CompanionGetInfoResult;
+  [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusResult;
+  [COMPANION_PREPARE_METHOD]: CompanionPrepareResult;
+  [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationResult;
+  [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionResult;
+  [COMPANION_LAUNCH_METHOD]: CompanionLaunchResult;
+  [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWriteResult;
+  [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinResult;
+  [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminateResult;
+  [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputResult;
+  [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentResult;
+  [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationResult;
 }
 
+export interface MiniProgramCapabilityProgressMap {
+  [NETWORK_DOWNLOAD_METHOD]: DownloadProgressPayload;
+  [COMPANION_PREPARE_METHOD]: CompanionPrepareProgress;
+}
+
+export type MiniProgramProgressMethod = keyof MiniProgramCapabilityProgressMap;
+export type MiniProgramCapabilityProgress<T extends MiniProgramProgressMethod> = MiniProgramCapabilityProgressMap[T];
+
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
 export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];

package/src/constants.ts

@@ -6,3 +6,6 @@ export const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe' as const;
 export const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report' as const;
 export const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation' as const;
 export const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress' as const;
+export const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output' as const;
+export const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit' as const;
+export const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost' as const;

package/src/guards.ts

@@ -1,6 +1,7 @@
 import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, SDK_HANDSHAKE_METHOD } from './constants';
 import type { MiniProgramBridgeMessage } from './bridge';
 import type {
+  CompanionPrepareProgress,
   DownloadProgressPayload,
   MiniProgramDirectoryDescriptor,
   MiniProgramDirectoryRef,
@@ -33,7 +34,7 @@ export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgram
   if (value.type === 'event') {
     if (!isNonEmptyString(value.method) || value.error !== undefined) return false;
     if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
     }
     return value.id === undefined || isNonEmptyString(value.id);
   }
@@ -75,7 +76,7 @@ export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramD
     return hasOnlyKeys(value, ['kind', 'handleId']);
   }
   return (
-    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
+    isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
   );
 }
 
@@ -133,6 +134,28 @@ export function isMiniProgramDownloadProgressPayload(value: unknown): value is D
   return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 
+export function isMiniProgramCompanionPrepareProgress(value: unknown): value is CompanionPrepareProgress {
+  if (!isRecord(value)) return false;
+  if (value.phase === 'downloading') {
+    return (
+      isNonNegativeSafeInteger(value.loaded) &&
+      (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+      hasOnlyKeys(value, ['phase', 'loaded', 'total'])
+    );
+  }
+  if (value.phase !== 'verifying' && value.phase !== 'extracting') return false;
+  return (
+    isNonNegativeSafeInteger(value.processed) &&
+    isNonNegativeSafeInteger(value.total) &&
+    value.processed <= value.total &&
+    hasOnlyKeys(value, ['phase', 'processed', 'total'])
+  );
+}
+
+export function isMiniProgramOperationProgressPayload(value: unknown): value is DownloadProgressPayload | CompanionPrepareProgress {
+  return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
+
 function isSDKHandshakePayload(value: unknown) {
   return isRecord(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }

package/src/payloads.ts

@@ -209,7 +209,6 @@ export interface NetworkRequestPayload {
   data?: unknown;
   headers?: MiniProgramNetworkHeaders;
   timeout?: number;
-  withCredentials?: boolean;
 }
 export interface NetworkResponsePayload<T = unknown> {
   data: T;
@@ -372,7 +371,6 @@ interface NetworkDownloadBasePayload {
   params?: MiniProgramNetworkParams;
   headers?: MiniProgramNetworkHeaders;
   timeout?: number;
-  withCredentials?: boolean;
   maxBytes?: number;
 }
 
@@ -484,3 +482,137 @@ export interface GetLeaderboardInfoResult {
   order: LeaderboardOrder;
   rankLimit: number;
 }
+
+/** 受管桌面程序可选能力。 */
+export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
+export type CompanionTarget = 'windows-x64' | 'macos-arm64';
+export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
+
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+export const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+export const COMPANION_ERROR_CODES = [
+  'COMPANION_UNSUPPORTED',
+  'COMPANION_NOT_DECLARED',
+  'COMPANION_TARGET_UNSUPPORTED',
+  'COMPANION_NOT_PREPARED',
+  'COMPANION_PREPARATION_CANCELLED',
+  'COMPANION_DOWNLOAD_FAILED',
+  'COMPANION_DESCRIPTOR_UNAVAILABLE',
+  'COMPANION_ARCHIVE_INVALID',
+  'COMPANION_INTEGRITY_FAILED',
+  'COMPANION_ENTRYPOINT_INVALID',
+  'COMPANION_USER_CANCELLED',
+  'COMPANION_ELEVATION_DENIED',
+  'COMPANION_OS_BLOCKED',
+  'COMPANION_LAUNCH_FAILED',
+  'COMPANION_SESSION_VERSION_MISMATCH',
+  'COMPANION_SESSION_OWNERSHIP_LOST',
+  'COMPANION_SESSION_EXITED',
+  'COMPANION_PIPE_CLOSED',
+  'COMPANION_OUTPUT_LIMIT',
+  'COMPANION_PROCESS_CRASHED',
+  'COMPANION_ATTACHMENT_NOT_FOUND',
+  'COMPANION_NOTIFICATION_UNAVAILABLE',
+  'COMPANION_TERMINATE_FAILED',
+] as const;
+export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
+
+export interface CompanionInfo {
+  alias: string;
+  displayName: string;
+  target: CompanionTarget;
+  capabilities: readonly CompanionCapability[];
+  archiveBytes: number;
+  signatureStatus: CompanionSignatureStatus;
+  /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
+  source?: 'local-dev' | 'released';
+}
+
+export interface CompanionErrorSummary {
+  code: CompanionErrorCode;
+  message: string;
+  retryable: boolean;
+}
+
+export type CompanionPrepareProgress =
+  | { phase: 'downloading'; loaded: number; total?: number }
+  | { phase: 'verifying'; processed: number; total: number }
+  | { phase: 'extracting'; processed: number; total: number };
+
+export type CompanionPreparationStatus =
+  | { state: 'not-prepared' }
+  | { state: 'preparing'; progress: CompanionPrepareProgress }
+  | { state: 'ready'; preparedAt: number }
+  | { state: 'failed'; error: CompanionErrorSummary };
+
+export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
+export type CompanionExit = { reason: 'exited'; exitCode: number } | { reason: Exclude<CompanionExitReason, 'exited'>; exitCode?: number };
+
+/** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
+export interface CompanionSessionSnapshot {
+  id: string;
+  alias: string;
+  target: CompanionTarget;
+  capabilities: readonly CompanionCapability[];
+  state: 'running';
+  controllerGeneration: number;
+}
+
+export interface CompanionAliasPayload {
+  alias: string;
+}
+export type CompanionGetInfoPayload = CompanionAliasPayload;
+export type CompanionGetInfoResult = CompanionInfo;
+export type CompanionGetPreparationStatusPayload = CompanionAliasPayload;
+export type CompanionGetPreparationStatusResult = CompanionPreparationStatus;
+export type CompanionPreparePayload = CompanionAliasPayload;
+export type CompanionPrepareResult = CompanionInfo;
+export type CompanionCancelPreparationPayload = CompanionAliasPayload;
+export type CompanionCancelPreparationResult = void;
+export type CompanionGetActiveSessionPayload = CompanionAliasPayload;
+export type CompanionGetActiveSessionResult = CompanionSessionSnapshot | undefined;
+export type CompanionLaunchPayload = CompanionAliasPayload;
+export type CompanionLaunchResult = CompanionSessionSnapshot;
+
+export interface CompanionSessionControllerPayload {
+  sessionId: string;
+  controllerGeneration: number;
+}
+export interface CompanionSessionWritePayload extends CompanionSessionControllerPayload {
+  data: Uint8Array;
+}
+export type CompanionSessionWriteResult = void;
+export type CompanionSessionCloseStdinPayload = CompanionSessionControllerPayload;
+export type CompanionSessionCloseStdinResult = void;
+export type CompanionSessionTerminatePayload = CompanionSessionControllerPayload;
+export type CompanionSessionTerminateResult = void;
+export interface CompanionSessionAckOutputPayload extends CompanionSessionControllerPayload {
+  stream: 'stdout' | 'stderr';
+  sequence: number;
+}
+export type CompanionSessionAckOutputResult = void;
+export interface CompanionOpenAttachmentPayload extends CompanionSessionControllerPayload {
+  id: string;
+}
+export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
+export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
+  category: CompanionNotificationCategory;
+}
+export type CompanionShowNotificationResult = void;
+
+export interface CompanionSessionOutputPayload extends CompanionSessionControllerPayload {
+  stream: 'stdout' | 'stderr';
+  sequence: number;
+  data: Uint8Array;
+}
+export interface CompanionSessionExitPayload {
+  sessionId: string;
+  exit: CompanionExit;
+}
+export interface CompanionSessionOwnershipLostPayload {
+  sessionId: string;
+  controllerGeneration: number;
+}

package/src/permission-catalog.ts

@@ -9,6 +9,7 @@ export const MINI_PROGRAM_PERMISSION_KEYS = [
   'clipboard',
   'leaderboard',
   'network',
+  'companion',
 ] as const;
 
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
@@ -146,6 +147,29 @@ export const MINI_PROGRAM_PERMISSION_CATALOG = [
     methods: ['network.request', 'network.download'],
     conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
   },
+  {
+    key: 'companion',
+    name: '桌面辅助应用',
+    description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+    access: 'platform-approval',
+    risk: 'high',
+    config: {},
+    methods: [
+      'companion.getInfo',
+      'companion.getPreparationStatus',
+      'companion.prepare',
+      'companion.cancelPreparation',
+      'companion.getActiveSession',
+      'companion.launch',
+      'companion.session.write',
+      'companion.session.closeStdin',
+      'companion.session.terminate',
+      'companion.session.ackOutput',
+      'companion.openAttachment',
+      'companion.showNotification',
+    ],
+    conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+  },
 ] as const satisfies readonly MiniProgramPermissionDefinition[];
 
 export const MINI_PROGRAM_NO_DECLARATION_METHODS = [

package/src/permissions.ts

@@ -42,7 +42,8 @@ export function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMin
     }
     seenKeys.add(key);
     if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-      if (!isRecord(rawEntry.config)) return { valid: false, permissions: {} };
+      // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+      // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
       continue;
     }
     if (key === 'network') {

package/types/bridge.d.ts

@@ -1,7 +1,8 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import { COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
+import type { CompanionSessionExitPayload, CompanionSessionOutputPayload, CompanionSessionOwnershipLostPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
-export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change';
+export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 export interface MiniProgramBridgeError {
     code: string;
     message: string;
@@ -59,12 +60,12 @@ export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage
     payload?: never;
     error?: never;
 }
-export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+export interface MiniProgramBridgeProgressMessage<TMethod extends MiniProgramProgressMethod = MiniProgramProgressMethod> extends MiniProgramBridgeMessage<MiniProgramCapabilityProgress<TMethod>> {
     version: 2;
     type: 'event';
     id: string;
     method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
-    payload: DownloadProgressPayload;
+    payload: MiniProgramCapabilityProgress<TMethod>;
     error?: never;
 }
 export interface MiniProgramEventPayloadMap {
@@ -91,4 +92,7 @@ export interface MiniProgramEventPayloadMap {
         isHeyboxAppLoggedIn: boolean;
     };
     user_info_authorization_change: UserInfoAuthorization;
+    [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+    [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+    [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }

package/types/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
+import type { CompanionCancelPreparationPayload, CompanionCancelPreparationResult, CompanionGetActiveSessionPayload, CompanionGetActiveSessionResult, CompanionGetInfoPayload, CompanionGetInfoResult, CompanionGetPreparationStatusPayload, CompanionGetPreparationStatusResult, CompanionLaunchPayload, CompanionLaunchResult, CompanionOpenAttachmentPayload, CompanionOpenAttachmentResult, CompanionPreparePayload, CompanionPrepareProgress, CompanionPrepareResult, CompanionSessionAckOutputPayload, CompanionSessionAckOutputResult, CompanionSessionCloseStdinPayload, CompanionSessionCloseStdinResult, CompanionSessionTerminatePayload, CompanionSessionTerminateResult, CompanionSessionWritePayload, CompanionSessionWriteResult, CompanionShowNotificationPayload, CompanionShowNotificationResult, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
 import type { MiniProgramPermissionRequirement } from './permission-catalog';
 export declare const AUTH_LOGIN_METHOD: "auth.login";
 export declare const USER_GET_INFO_METHOD: "user.getInfo";
@@ -41,6 +41,18 @@ export declare const CLOUD_LEADERBOARD_GET_LIST_METHOD: "cloud.leaderboard.getLi
 export declare const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.getCurrentUserEntry";
 export declare const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.deleteCurrentUserEntry";
 export declare const CLOUD_LEADERBOARD_GET_INFO_METHOD: "cloud.leaderboard.getInfo";
+export declare const COMPANION_GET_INFO_METHOD: "companion.getInfo";
+export declare const COMPANION_GET_PREPARATION_STATUS_METHOD: "companion.getPreparationStatus";
+export declare const COMPANION_PREPARE_METHOD: "companion.prepare";
+export declare const COMPANION_CANCEL_PREPARATION_METHOD: "companion.cancelPreparation";
+export declare const COMPANION_GET_ACTIVE_SESSION_METHOD: "companion.getActiveSession";
+export declare const COMPANION_LAUNCH_METHOD: "companion.launch";
+export declare const COMPANION_SESSION_WRITE_METHOD: "companion.session.write";
+export declare const COMPANION_SESSION_CLOSE_STDIN_METHOD: "companion.session.closeStdin";
+export declare const COMPANION_SESSION_TERMINATE_METHOD: "companion.session.terminate";
+export declare const COMPANION_SESSION_ACK_OUTPUT_METHOD: "companion.session.ackOutput";
+export declare const COMPANION_OPEN_ATTACHMENT_METHOD: "companion.openAttachment";
+export declare const COMPANION_SHOW_NOTIFICATION_METHOD: "companion.showNotification";
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
@@ -54,8 +66,9 @@ export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_L
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
 export type MiniProgramCloudMethod = typeof CLOUD_LEADERBOARD_SUBMIT_METHOD | typeof CLOUD_LEADERBOARD_GET_LIST_METHOD | typeof CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_GET_INFO_METHOD;
-export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramFilesMethod | MiniProgramFileMethod | MiniProgramDirectoryMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod;
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'files' | 'file' | 'directory' | 'ui' | 'device' | 'navigation' | 'cloud';
+export type MiniProgramCompanionMethod = typeof COMPANION_GET_INFO_METHOD | typeof COMPANION_GET_PREPARATION_STATUS_METHOD | typeof COMPANION_PREPARE_METHOD | typeof COMPANION_CANCEL_PREPARATION_METHOD | typeof COMPANION_GET_ACTIVE_SESSION_METHOD | typeof COMPANION_LAUNCH_METHOD | typeof COMPANION_SESSION_WRITE_METHOD | typeof COMPANION_SESSION_CLOSE_STDIN_METHOD | typeof COMPANION_SESSION_TERMINATE_METHOD | typeof COMPANION_SESSION_ACK_OUTPUT_METHOD | typeof COMPANION_OPEN_ATTACHMENT_METHOD | typeof COMPANION_SHOW_NOTIFICATION_METHOD;
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramFilesMethod | MiniProgramFileMethod | MiniProgramDirectoryMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod | MiniProgramCompanionMethod;
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'files' | 'file' | 'directory' | 'ui' | 'device' | 'navigation' | 'cloud' | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 export interface MiniProgramCapabilityDefinition {
     method: MiniProgramBridgeMethod;
@@ -423,7 +436,16 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
         readonly permissions: readonly ["leaderboard"];
     };
     readonly risk: "low";
-}];
+}, ...{
+    method: "companion.getInfo" | "companion.getPreparationStatus" | "companion.prepare" | "companion.cancelPreparation" | "companion.getActiveSession" | "companion.launch" | "companion.session.write" | "companion.session.closeStdin" | "companion.session.terminate" | "companion.session.ackOutput" | "companion.openAttachment" | "companion.showNotification";
+    module: "companion";
+    capability: "companion.getInfo" | "companion.getPreparationStatus" | "companion.prepare" | "companion.cancelPreparation" | "companion.getActiveSession" | "companion.launch" | "companion.session.write" | "companion.session.closeStdin" | "companion.session.terminate" | "companion.session.ackOutput" | "companion.openAttachment" | "companion.showNotification";
+    requirement: {
+        kind: "all";
+        permissions: "companion"[];
+    };
+    risk: "high";
+}[]];
 export interface MiniProgramCapabilityPayloadMap {
     [AUTH_LOGIN_METHOD]: LoginPayload;
     [USER_GET_INFO_METHOD]: GetUserInfoPayload;
@@ -466,6 +488,18 @@ export interface MiniProgramCapabilityPayloadMap {
     [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryPayload | undefined;
     [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryPayload | undefined;
     [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoPayload | undefined;
+    [COMPANION_GET_INFO_METHOD]: CompanionGetInfoPayload;
+    [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusPayload;
+    [COMPANION_PREPARE_METHOD]: CompanionPreparePayload;
+    [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationPayload;
+    [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionPayload;
+    [COMPANION_LAUNCH_METHOD]: CompanionLaunchPayload;
+    [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWritePayload;
+    [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinPayload;
+    [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminatePayload;
+    [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputPayload;
+    [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentPayload;
+    [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationPayload;
 }
 export interface MiniProgramCapabilityResultMap {
     [AUTH_LOGIN_METHOD]: LoginResult;
@@ -509,6 +543,24 @@ export interface MiniProgramCapabilityResultMap {
     [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
     [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
     [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
+    [COMPANION_GET_INFO_METHOD]: CompanionGetInfoResult;
+    [COMPANION_GET_PREPARATION_STATUS_METHOD]: CompanionGetPreparationStatusResult;
+    [COMPANION_PREPARE_METHOD]: CompanionPrepareResult;
+    [COMPANION_CANCEL_PREPARATION_METHOD]: CompanionCancelPreparationResult;
+    [COMPANION_GET_ACTIVE_SESSION_METHOD]: CompanionGetActiveSessionResult;
+    [COMPANION_LAUNCH_METHOD]: CompanionLaunchResult;
+    [COMPANION_SESSION_WRITE_METHOD]: CompanionSessionWriteResult;
+    [COMPANION_SESSION_CLOSE_STDIN_METHOD]: CompanionSessionCloseStdinResult;
+    [COMPANION_SESSION_TERMINATE_METHOD]: CompanionSessionTerminateResult;
+    [COMPANION_SESSION_ACK_OUTPUT_METHOD]: CompanionSessionAckOutputResult;
+    [COMPANION_OPEN_ATTACHMENT_METHOD]: CompanionOpenAttachmentResult;
+    [COMPANION_SHOW_NOTIFICATION_METHOD]: CompanionShowNotificationResult;
 }
+export interface MiniProgramCapabilityProgressMap {
+    [NETWORK_DOWNLOAD_METHOD]: DownloadProgressPayload;
+    [COMPANION_PREPARE_METHOD]: CompanionPrepareProgress;
+}
+export type MiniProgramProgressMethod = keyof MiniProgramCapabilityProgressMap;
+export type MiniProgramCapabilityProgress<T extends MiniProgramProgressMethod> = MiniProgramCapabilityProgressMap[T];
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
 export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];

package/types/constants.d.ts

@@ -6,3 +6,6 @@ export declare const RUNTIME_LOCATION_PROBE_METHOD: "runtime.location.probe";
 export declare const SDK_LOCATION_REPORT_METHOD: "sdk.location.report";
 export declare const SDK_CSP_VIOLATION_METHOD: "sdk.csp.violation";
 export declare const MINI_PROGRAM_OPERATION_PROGRESS_METHOD: "operation.progress";
+export declare const COMPANION_SESSION_OUTPUT_EVENT: "companion.session.output";
+export declare const COMPANION_SESSION_EXIT_EVENT: "companion.session.exit";
+export declare const COMPANION_SESSION_OWNERSHIP_LOST_EVENT: "companion.session.ownershipLost";

package/types/guards.d.ts

@@ -1,5 +1,5 @@
 import type { MiniProgramBridgeMessage } from './bridge';
-import type { DownloadProgressPayload, MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramPathRootRef } from './payloads';
+import type { CompanionPrepareProgress, DownloadProgressPayload, MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramPathRootRef } from './payloads';
 export declare function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage;
 export declare function isMiniProgramRelativePath(value: unknown): value is string;
 export declare function isMiniProgramPathRootRef(value: unknown): value is MiniProgramPathRootRef;
@@ -11,3 +11,5 @@ export declare function isMiniProgramFileSystemEntityDescriptor(value: unknown):
 export declare function isMiniProgramByteArray(value: unknown): value is Uint8Array;
 export declare function isMiniProgramFileStat(value: unknown): value is MiniProgramFileStat;
 export declare function isMiniProgramDownloadProgressPayload(value: unknown): value is DownloadProgressPayload;
+export declare function isMiniProgramCompanionPrepareProgress(value: unknown): value is CompanionPrepareProgress;
+export declare function isMiniProgramOperationProgressPayload(value: unknown): value is DownloadProgressPayload | CompanionPrepareProgress;