@native-engagement/sdk 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,5 +1,18 @@
 // Generated by dts-bundle-generator v9.5.1
 
+declare const installationModuleIds: readonly [
+	"android.wechat",
+	"android.whatsapp",
+	"bridge.wechat",
+	"bridge.mail",
+	"bridge.browser",
+	"api.youtube",
+	"api.tiktok",
+	"browser.xiaohongshu",
+	"browser.douyin",
+	"browser.tiktok"
+];
+export type InstallationModuleId = typeof installationModuleIds[number];
 export type ContractRisk = "READ_ONLY" | "DOMAIN_WRITE" | "REVIEW_REQUIRED" | "EXTERNAL_ACTION" | "ADMINISTRATION";
 export type ContractKind = "SCHEMA" | "QUERY" | "COMMAND" | "SEARCH" | "ENQUIRY" | "EVENT" | "CAPABILITY";
 export type ContractAvailability = "AVAILABLE" | "PLANNED";
@@ -64,6 +77,145 @@ export interface McpToolDefinition {
 	readonly annotations?: unknown;
 	readonly _meta?: unknown;
 }
+export type InteractionMailProvider = "ALIMAIL" | "TENCENT_EXMAIL" | "GMAIL" | "ICLOUD" | "ZOHO" | "MICROSOFT" | "CUSTOM";
+export interface InteractionMailEndpoint {
+	host: string;
+	port: number;
+	security: "TLS" | "STARTTLS" | "NONE";
+	username?: string;
+}
+export interface InteractionMailConfiguration {
+	profileRef?: string;
+	expectedRevision?: number;
+	displayName?: string;
+	provider?: InteractionMailProvider;
+	mailbox?: string;
+	connection?: {
+		imap: InteractionMailEndpoint;
+		smtp: InteractionMailEndpoint;
+	};
+	presetRef?: string;
+	presetRevision?: number;
+	region?: "CN" | "HK";
+	folders?: {
+		inbox: string;
+		drafts?: string;
+		sent?: string;
+	};
+}
+export interface InteractionEnvironmentInstallation {
+	environmentRef: string;
+	platform: "DARWIN" | "LINUX" | "WINDOWS";
+	architecture: "ARM64" | "X64";
+	moduleIds: (InstallationModuleId | "api.weixin" | "media.shared")[];
+	installationRef?: string;
+	expectedFingerprint?: string;
+	deviceRef?: string;
+	planDigest?: string;
+}
+export interface InteractionAccountConnection {
+	connectionRef: string;
+	profileRef: string;
+	deviceRef: string;
+	resourceRef: string;
+	expectedPlacementRevision: number;
+	mode: "LOGIN" | "RENEW";
+	allowAgentVision: boolean;
+	maximumChallengeAttempts: number;
+}
+export interface InteractionDevicePlacement {
+	nodeRef: string;
+	profileRef: string;
+	expectedPlacementRevision: number;
+	resourceRef: string;
+	expectedNodeGeneration: number;
+	environmentGeneration: number;
+	expectedHostBindingDigest: string;
+	expectedModuleDigest: string;
+}
+export interface InteractionAccountSetup {
+	setupRef: string;
+	deviceRef: string;
+	moduleId: "android.wechat" | "android.whatsapp";
+	displayName: string;
+	installationRef?: string;
+	expectedNodeGeneration?: number;
+	expectedFingerprint?: string;
+}
+/** 公开参数表达闭合的窄意图，既不接收秘密，也不允许调用者选择任意业务合同。 */
+export type InteractionOperation = {
+	type: "MAIL_CONFIGURATION";
+	payload: InteractionMailConfiguration;
+} | {
+	type: "MESSAGE_REVIEW";
+	payload: {
+		engagementRef: string;
+		messageRef: string;
+		version: number;
+		contentDigest: string;
+	};
+} | {
+	type: "ENVIRONMENT_INSTALLATION";
+	payload: InteractionEnvironmentInstallation;
+} | {
+	type: "NODE_PAIRING";
+	payload: {
+		pairingRef: string;
+		expectedRevision: number;
+		expectedFingerprint: string;
+	};
+} | {
+	type: "DEVICE_PLACEMENT";
+	payload: InteractionDevicePlacement;
+} | {
+	type: "ACCOUNT_SETUP";
+	payload: InteractionAccountSetup;
+} | {
+	type: "ACCOUNT_CONNECTION";
+	payload: InteractionAccountConnection;
+} | {
+	type: "FEEDBACK";
+	payload: {
+		text: string;
+	};
+};
+export interface InteractionRequestInput {
+	idempotencyKey: string;
+	interactionRef: string;
+	title: string;
+	rationale: string;
+	operation: InteractionOperation;
+	reviewerPrincipalRef?: string;
+	expiresInSeconds?: number;
+}
+export interface InteractionExpectedInput {
+	idempotencyKey: string;
+	interactionRef: string;
+	expectedRevision: number;
+	expectedRequestDigest: string;
+}
+export interface InteractionReviseInput extends InteractionExpectedInput {
+	title?: string;
+	rationale?: string;
+	operation: InteractionOperation;
+}
+export interface InteractionAssignInput extends InteractionExpectedInput {
+	reviewerPrincipalRef: string;
+}
+export interface InteractionRespondInput extends InteractionExpectedInput {
+	action: "APPROVE" | "REJECT";
+	rationale: string;
+}
+export interface InteractionCancelInput extends InteractionExpectedInput {
+	rationale: string;
+}
+export interface InteractionGetInput {
+	interactionRef: string;
+}
+export interface InteractionListInput {
+	limit?: number;
+	cursor?: string;
+}
 /** Public DTOs shared by the Agent SDK; runtime validation is the canonical JSON Schema. */
 export type ProspectTemporalStatus = "CURRENT" | "HISTORICAL";
 export interface ProspectObservation {
@@ -190,33 +342,23 @@ declare const BROWSER_SOCIAL_PLATFORMS: readonly [
 	"DOUYIN",
 	"TIKTOK"
 ];
-export interface AgentStackScope {
-	readonly authorityRef: string;
-	readonly sourcePrincipal: Readonly<{
-		issuer: string;
-		subject: string;
-	}>;
-	readonly tenantId: string;
-	readonly workspaceId: string;
-	readonly projectId: string;
-	readonly businessAgentId: string;
-	readonly businessAgentVersionId: string;
-	/** 经签名的上游服务凭据租约 ID；正式生产端配对要求此字段以隔离轮换后的旧断言。 */
-	readonly sourceCredentialId?: string;
+/** Browser-safe shared approval representation; no host paths, locators or bytes. */
+export interface MessageAttachment {
+	readonly assetRef: string;
+	readonly sourceVersion: string;
+	readonly digest: string;
+	readonly mediaType: string;
+	readonly byteLength: number;
+	readonly filename: string;
+	readonly presentation?: "VOICE_NOTE" | "IMAGE" | "VIDEO";
 }
-export interface TenantContextInput {
-	readonly tenantId?: string | undefined;
-	readonly principalRef?: string | undefined;
-	readonly actorRef?: string | undefined;
-	readonly authorizationScopes?: readonly string[] | undefined;
-	readonly projectRef?: string | undefined;
-	readonly workspaceRef?: string | undefined;
-	/** Signature-verified JWT issuer, never a caller-supplied business payload. */
-	readonly identityIssuer?: string | undefined;
-	/** Signature-verified JWT subject, never a caller-supplied business payload. */
-	readonly identitySubject?: string | undefined;
-	/** 只由验证签名的 Agent Stack 适配器产生，HTTP 业务 payload 不得提供。 */
-	readonly agentStack?: AgentStackScope | undefined;
+type MessageAttachmentChoice = Pick<MessageAttachment, "assetRef" | "filename" | "presentation">;
+/** 由已安装适配器协商的宿主需求；业务身份、设备检查及资源租约仍各自生效。 */
+export interface NodeExecutionRequirements {
+	readonly protocol: 1;
+	readonly hostSleepMonitor: boolean;
+	readonly hostDisplay: boolean;
+	readonly hostDesktopSession: boolean;
 }
 /** The exact accessible display belongs to its outer source row, without author or parent identity. */
 export interface NativeQuotedDisplay {
@@ -248,6 +390,58 @@ export interface NativeRenderedMedia {
 	readonly authorIdentity: "NOT_ATTESTED";
 	readonly parentMessageIdentity: "NOT_ATTESTED";
 }
+export interface AgentStackScope {
+	readonly authorityRef: string;
+	readonly sourcePrincipal: Readonly<{
+		issuer: string;
+		subject: string;
+	}>;
+	readonly tenantId: string;
+	readonly workspaceId: string;
+	readonly projectId: string;
+	readonly businessAgentId: string;
+	readonly businessAgentVersionId: string;
+	/** 经签名的上游服务凭据租约 ID；正式生产端配对要求此字段以隔离轮换后的旧断言。 */
+	readonly sourceCredentialId?: string;
+}
+export interface TenantContextInput {
+	readonly tenantId?: string | undefined;
+	readonly principalRef?: string | undefined;
+	readonly actorRef?: string | undefined;
+	readonly authorizationScopes?: readonly string[] | undefined;
+	readonly projectRef?: string | undefined;
+	readonly workspaceRef?: string | undefined;
+	/** Signature-verified JWT issuer, never a caller-supplied business payload. */
+	readonly identityIssuer?: string | undefined;
+	/** Signature-verified JWT subject, never a caller-supplied business payload. */
+	readonly identitySubject?: string | undefined;
+	/** 只由验证签名的 Agent Stack 适配器产生，HTTP 业务 payload 不得提供。 */
+	readonly agentStack?: AgentStackScope | undefined;
+}
+/** EMAIL 专属的内嵌映射；文件字节身份仍由原附件六字段清单拥有。 */
+export interface EmailInlineImage {
+	readonly cid: string;
+	readonly assetRef: string;
+}
+export interface MailSignatureImage extends EmailInlineImage {
+	readonly filename: string;
+}
+/** 草稿中冻结的签名快照；发送和核查不再读取可变模板。 */
+export interface FrozenMailSignature {
+	readonly signatureRef: string;
+	readonly version: number;
+	readonly digest: string;
+	readonly profileRef: string;
+	readonly text: string;
+	readonly html?: string;
+	readonly inlineImages: readonly EmailInlineImage[];
+}
+export interface EmailRichContent {
+	readonly text: string;
+	readonly html?: string;
+	readonly inlineImages?: readonly EmailInlineImage[];
+	readonly signature?: FrozenMailSignature;
+}
 export interface CommunicationPolicyBasis {
 	readonly policyRef: string;
 	readonly version: number;
@@ -436,6 +630,27 @@ export interface EngagementControl {
 	readonly resumedAt?: string;
 	readonly sessionCorrelationRef?: string;
 }
+/** 模板属于创建时的精确租户范围，媒体只保存已有 Asset 的选择，不拥有字节。 */
+export interface MailSignatureTemplate {
+	readonly tenantId: string;
+	readonly projectRef?: string;
+	readonly workspaceRef?: string;
+	readonly signatureRef: string;
+	readonly version: number;
+	readonly displayName: string;
+	readonly enabled: boolean;
+	readonly text: string;
+	readonly html?: string;
+	readonly inlineImages: readonly MailSignatureImage[];
+	readonly digest: string;
+	readonly configuredAt: string;
+	readonly configuredBy: string;
+}
+export interface MailSignaturePage {
+	readonly items: readonly Pick<MailSignatureTemplate, "signatureRef" | "version" | "displayName" | "enabled" | "digest">[];
+	readonly nextOffset: number | null;
+	readonly total: number;
+}
 export interface WechatAutonomy {
 	readonly enabled: boolean;
 	readonly version: number;
@@ -1193,16 +1408,6 @@ export interface CommunicationMessage {
 	readonly message: MessageProjection;
 	readonly source: SourceObservation;
 }
-/** Browser-safe shared approval representation; no host paths, locators or bytes. */
-export interface MessageAttachment {
-	readonly assetRef: string;
-	readonly sourceVersion: string;
-	readonly digest: string;
-	readonly mediaType: string;
-	readonly byteLength: number;
-	readonly filename: string;
-	readonly presentation?: "VOICE_NOTE" | "IMAGE" | "VIDEO";
-}
 export type SourceMessagePart = {
 	readonly partRef: string;
 	readonly kind: "TEXT";
@@ -1330,6 +1535,51 @@ export interface SourceBasis {
 	readonly messageRef: string;
 	readonly headFactRef: string;
 }
+export interface DeliveredEmailAttachment extends MessageAttachment {
+	readonly remoteAttachmentRef: string;
+}
+export type EmailMessageStatus = "DRAFT" | "APPROVED" | "REJECTED" | "QUEUED" | "CANCELLED" | "ACCEPTED" | "UNCERTAIN" | "FAILED";
+/** 原 Work 的提交依据；与内容生成来源区分，外部命令不能自行声明。 */
+export interface EmailWorkSource {
+	readonly workRef: string;
+	readonly kind: "REPLY" | "FOLLOW_UP" | "CONTACT";
+	readonly taskOrigin?: TaskCommunicationOrigin;
+	readonly communicationPolicyBasis?: CommunicationPolicyBasis;
+}
+export interface EmailMessageProjection extends EmailRichContent {
+	readonly taskOrigin?: TaskCommunicationOrigin;
+	readonly workSource?: EmailWorkSource;
+	readonly sourceBasis?: SourceBasis;
+	readonly tenantId: string;
+	readonly engagementRef: string;
+	readonly messageRef: string;
+	readonly conversationRef?: string;
+	readonly version: number;
+	readonly contentDigest: string;
+	readonly routeRef: string;
+	readonly recipientAddress: string;
+	readonly senderParticipantRef: string;
+	readonly recipientParticipantRef: string;
+	readonly subject: string;
+	readonly text: string;
+	readonly replyToMessageRef?: string;
+	readonly followUpOfMessageRef?: string;
+	readonly followUpPlanVersion?: number;
+	readonly attachments?: readonly MessageAttachment[];
+	readonly deliveredAttachments?: readonly DeliveredEmailAttachment[];
+	readonly status: EmailMessageStatus;
+	readonly createdAt: string;
+	readonly updatedAt: string;
+	readonly reviewedBy?: string;
+	readonly reviewerKind?: "HUMAN";
+	readonly approvalExpiresAt?: string;
+	readonly profileRef?: string;
+	readonly sendRequestRef?: string;
+	readonly correlationRef?: string;
+	readonly internetMessageId?: string;
+	readonly observedAt?: string;
+	readonly followUpDueAt?: string;
+}
 /** 原文本消息模型；旧 WechatMessage 继续作为兼容名称。 */
 export type TextMessageStatus = "DRAFT" | "APPROVED" | "REJECTED" | "QUEUED" | "CLIENT_VISIBLE" | "UNCERTAIN" | "FAILED" | "CANCELLED";
 export interface TaskCommunicationOrigin {
@@ -1378,7 +1628,133 @@ export interface TextChannelMessage {
 	readonly hostEvidenceDigest?: string;
 }
 export type CommunicationChannel = "EMAIL" | "WECHAT" | "WHATSAPP" | "SOCIAL";
+declare const DESKTOP_ACTION_KINDS: readonly [
+	"MOMENTS_PUBLISH",
+	"MOMENTS_COMMENT",
+	"MOMENTS_REPLY",
+	"MOMENTS_LIKE",
+	"MOMENTS_UNLIKE",
+	"MOMENTS_DELETE",
+	"MOMENTS_COMMENT_DELETE",
+	"CHANNELS_PUBLISH",
+	"CHANNELS_COMMENT",
+	"CHANNELS_REPLY",
+	"CHANNELS_LIKE",
+	"CHANNELS_UNLIKE",
+	"CHANNELS_COMMENT_DELETE",
+	"WORKS_PUBLISH",
+	"WORKS_COMMENT",
+	"WORKS_REPLY",
+	"WORKS_LIKE",
+	"WORKS_UNLIKE",
+	"WORKS_DELETE",
+	"WORKS_COMMENT_DELETE",
+	"CONTACT_REMARK",
+	"CONTACT_DELETE",
+	"GROUP_RENAME",
+	"GROUP_ANNOUNCEMENT",
+	"GROUP_LEAVE",
+	"GROUP_MUTE",
+	"GROUP_UNMUTE",
+	"GROUP_PIN",
+	"GROUP_UNPIN",
+	"CONTACT_REQUEST",
+	"CONTACT_ACCEPT",
+	"GROUP_CREATE",
+	"GROUP_INVITE",
+	"MESSAGE_FORWARD",
+	"CONTACT_SHARE",
+	"MOMENTS_SHARE",
+	"CHANNELS_SHARE",
+	"WORKS_SHARE"
+];
+export type DesktopActionKind = typeof DESKTOP_ACTION_KINDS[number];
+declare const DESKTOP_NATIVE_PRESENTATIONS: readonly [
+	"IMAGE",
+	"VIDEO",
+	"VOICE_NOTE"
+];
+export type DesktopNativePresentation = typeof DESKTOP_NATIVE_PRESENTATIONS[number];
 declare const EXECUTION_NODE_PROTOCOL = "ne-execution-node/1.0";
+declare const EXECUTION_NODE_MODULE = "android.whatsapp.read";
+export interface NodeResourceAdvertisement extends WechatOnboardingProtocols {
+	readonly weixinOfficialReadProtocol?: 1;
+	readonly executionRequirements?: NodeExecutionRequirements;
+	readonly desktopTaskContextProtocol?: 1;
+	readonly desktopTaskNavigationProtocol?: 1;
+	readonly desktopConversationLocateProtocol?: 1;
+	readonly desktopConversationResolveProtocol?: 1;
+	readonly desktopConversationDiscoveryProtocol?: 1;
+	readonly desktopConversationSelectProtocol?: 1;
+	readonly desktopConversationBrowseProtocol?: 1;
+	readonly nativeTaskNavigationProtocol?: 1;
+	readonly nativeCancelledDraftProtocol?: 1;
+	readonly nativeMediaSendProtocol?: 1;
+	/** 固定 Facebook Profile 观察与人工恢复协议，不授予营销写入。 */
+	readonly browserProfileProtocol?: 1;
+	readonly browserProfileTaskProtocol?: 1;
+	readonly browserProfileContentProtocol?: 1;
+	readonly browserProfilePostsProtocol?: 1;
+	readonly browserProfilePostDetailProtocol?: 1;
+	readonly browserProfileCommentsProtocol?: 1;
+	readonly browserProfileCurrentCommentsProtocol?: 1;
+	readonly browserProfileSearchProtocol?: 1;
+	readonly browserProfileNavigationProtocol?: 1;
+	readonly facebookReplyProtocol?: 1;
+	readonly browserProfileActivityProtocol?: 1;
+	readonly nativeRenderedWindowBoundaryProtocol?: 1;
+	readonly nativeRenderedMediaProtocol?: 1;
+	localResourceDigest: string;
+	environmentGeneration: number;
+	hostRef: string;
+	profileRef: string;
+	accountRef: string;
+	sessionRef: string;
+	capabilityRef: string;
+	hostBindingDigest: string;
+	application: "weixin" | "whatsapp" | "youtube" | "tiktok" | "wechat" | "browser" | "mail" | "xiaohongshu" | "douyin";
+	externalAccountRef?: string;
+	bridgeBindingJson?: string;
+	bridgeRuntimeKind?: "DESKTOP" | "BROWSER" | "API" | "MAIL";
+	mailConfigurationDigest?: string;
+	moduleId: typeof EXECUTION_NODE_MODULE | "android.whatsapp.message" | "android.wechat.read" | "android.wechat.message" | "api.weixin" | "api.youtube" | "api.tiktok" | "bridge.wechat" | "bridge.browser" | "bridge.mail" | "browser.xiaohongshu" | "browser.douyin" | "browser.tiktok";
+	moduleVersion: "1.0.0";
+	moduleDigest: string;
+	enabled: boolean;
+	supportsDisplayOff: boolean;
+	supportsLocked: boolean;
+	supportsNativeCapture?: boolean;
+	supportsNativeCaption?: boolean;
+	supportsNativeBytes?: boolean;
+	supportsSourceBytes?: boolean;
+	browserSocialProtocol?: 1;
+	browserSocialDirectMediaKinds?: readonly ("IMAGE" | "VIDEO")[];
+	browserSocialActions?: readonly ("READ" | "COMMENT" | "REPLY" | "DIRECT" | "PUBLISH" | "SCHEDULE_CANCEL" | "SCHEDULE_RESCHEDULE")[];
+	xiaohongshuDirectMediaProtocol?: 1;
+	xiaohongshuDirectMediaKinds?: readonly ("IMAGE" | "VIDEO" | "VOICE_NOTE")[];
+	desktopFileSendProtocol?: 1;
+	nativeWechatMultiSendProtocol?: 1;
+	wechatPhysicalRecoveryProtocol?: 1;
+	desktopMediaPresentations?: readonly DesktopNativePresentation[];
+	desktopActionProtocol?: 1;
+	desktopActionKinds?: readonly DesktopActionKind[];
+	/** Actual protected host describe/probe negotiated personal WeChat ID verification v1. */
+	supportsWechatContactIdentity?: boolean;
+	wechatLocalIdentityProtocol?: 1;
+	/** Independent complete PERSONAL LOCAL5+CONTACT3 protocol; never inferred from the GROUP capability. */
+	wechatPersonalLocalIdentityProtocol?: 1;
+	/** Actual protected host describe/probe negotiated the bounded unbound Social read protocol v1. */
+	supportsWechatSocialRead?: boolean;
+	/** Absent preserves the legacy current-page-only v1 advertisement. */
+	wechatSocialReadProtocol?: 2;
+	wechatSocialTargetRegistrationProtocol?: 1;
+	wechatMomentsPublicationProtocol?: 1;
+	wechatOfficialReadProtocol?: 1;
+	wechatChannelsFeedReadProtocol?: 1;
+	nativeVoiceObservationProtocol?: 1 | 2;
+	wechatOutboundDisplayProtocol?: 1;
+	wechatQuotedHistoryProtocol?: 1 | 2;
+}
 export interface NodeProof {
 	protocol: typeof EXECUTION_NODE_PROTOCOL;
 	tenantId: string;
@@ -1393,6 +1769,61 @@ export interface NodeProof {
 	bodyDigest: string;
 	signature: string;
 }
+/** 独立受保护端口资格；既有能力或环境变量不能推导这些版本。 */
+export interface WechatOnboardingProtocols {
+	readonly wechatGroupBindingProtocol?: 1;
+	readonly wechatGroupAuthorProtocol?: 1;
+	readonly wechatSourceRebuildProtocol?: 1;
+	readonly wechatTargetContinuityProtocol?: 1;
+	readonly wechatSelectionNavigationProtocol?: 1;
+	readonly nativeBootstrapProtocol?: 1;
+	readonly wechatConversationDiscoveryProtocol?: 1;
+	readonly wechatHomeLocalIdentityProtocol?: 1;
+	readonly wechatBindingContinuityProtocol?: 1;
+	readonly wechatSourceWindowCommitProtocol?: 1;
+}
+/** 通用交互只关联原业务操作、人类决定和应用回执，不承载模型会话或设备秘密。 */
+export type EngagementInteractionOperationType = "MAIL_CONFIGURATION" | "MESSAGE_REVIEW" | "ENVIRONMENT_INSTALLATION" | "NODE_PAIRING" | "DEVICE_PLACEMENT" | "ACCOUNT_SETUP" | "ACCOUNT_CONNECTION" | "FEEDBACK";
+export interface EngagementInteractionOperation {
+	type: EngagementInteractionOperationType;
+	payload: Record<string, unknown>;
+}
+export type EngagementInteractionState = "PENDING" | "DECIDED" | "APPLYING" | "APPLIED" | "REJECTED" | "CANCELLED" | "EXPIRED" | "FAILED" | "UNKNOWN";
+export interface EngagementInteractionApplication {
+	state: "NOT_STARTED" | "APPLYING" | "APPLIED" | "WAITING" | "FAILED" | "UNKNOWN";
+	result: Record<string, unknown> | null;
+	receiptRefs: string[];
+	blockers: string[];
+}
+export interface EngagementInteraction {
+	protocol: "native-engagement.interaction/1";
+	schemaVersion: 1;
+	tenantId: string;
+	interactionRef: string;
+	revision: number;
+	requestDigest: string;
+	requesterPrincipalRef: string;
+	reviewerPrincipalRef: string | null;
+	projectRef: string | null;
+	workspaceRef: string | null;
+	kind: "CONFIGURATION" | "APPROVAL" | "INSTALLATION" | "AUTHENTICATION" | "FEEDBACK";
+	title: string;
+	rationale: string;
+	operation: EngagementInteractionOperation;
+	state: EngagementInteractionState;
+	createdAt: string;
+	expiresAt: string;
+	reviewPath: string;
+	decision: {
+		decisionRef: string;
+		principalRef: string;
+		action: "APPROVE" | "REJECT";
+		rationale: string;
+		requestDigest: string;
+		decidedAt: string;
+	} | null;
+	application: EngagementInteractionApplication;
+}
 export type WorkbenchSummary = ({
 	readonly prospectRef: string;
 	readonly ownership?: never;
@@ -1426,6 +1857,185 @@ export interface ContractExecutionRequest {
 	readonly payload?: Readonly<Record<string, unknown>> | undefined;
 	readonly context?: TenantContextInput | undefined;
 }
+/** 签名 Node 心跳观察的宿主系统，不能从安装意图推断；旧节点明确保留 UNKNOWN。 */
+export interface ExecutionDeviceSystem {
+	schemaVersion: 1;
+	platform: "DARWIN" | "LINUX" | "WINDOWS" | "OTHER" | "UNKNOWN";
+	architecture: "ARM64" | "X64" | "OTHER" | "UNKNOWN";
+	observedAt: string | null;
+	currentness: "CURRENT" | "EXPIRED" | "NOT_OBSERVED";
+}
+/** Device 是原 Node 的授权投影；登记、在线、模块及账号认证分别保留真实证据。 */
+export interface ExecutionDeviceView {
+	protocol: "native-engagement.device/1";
+	tenantId: string;
+	deviceRef: string;
+	nodeRef: string;
+	installationRef: string;
+	fingerprint: string;
+	generation: number;
+	online: boolean;
+	state: "PAIRED" | "REVOKED";
+	lastSeenAt: string | null;
+	system?: ExecutionDeviceSystem;
+	resources: readonly (NodeResourceAdvertisement & {
+		resourceRef: string;
+		blockers: string[];
+	})[];
+	blockers: string[];
+}
+export interface EnvironmentRequest {
+	environmentRef: string;
+	platform: "DARWIN" | "LINUX" | "WINDOWS";
+	architecture: "ARM64" | "X64";
+	moduleIds: string[];
+	installationRef?: string;
+	expectedFingerprint?: string;
+	deviceRef?: string;
+	planDigest?: string;
+}
+export interface DeviceResourceLimits {
+	cpuPercent: number;
+	memoryMb: number;
+	maximumProcesses: number;
+	maximumRuntimeSeconds: number;
+}
+export interface ExecutionEnvironmentView extends Omit<EnvironmentRequest, "installationRef" | "deviceRef"> {
+	protocol: "native-engagement.environment/1";
+	tenantId: string;
+	interactionRef: string;
+	installationRef: string | null;
+	deviceRef: string | null;
+	planDigest: string;
+	state: "APPROVAL_REQUIRED" | "BOOTSTRAP_REQUIRED" | "PAIRING_REQUIRED" | "READY" | "BLOCKED";
+	installerUrl: string | null;
+	bootstrapUrl: string | null;
+	artifactDigest: string | null;
+	signatureRef: string | null;
+	resourceLimits: DeviceResourceLimits | null;
+	prerequisites: string[];
+	blockers: string[];
+	online: boolean | null;
+	qualification: {
+		artifact: "NOT_PROVEN" | "VERIFIED";
+		resourceLimits: "NOT_PROVEN" | "VERIFIED";
+	};
+	bootstrapRequest: {
+		schemaVersion: 1;
+		tenantId: string;
+		serviceOrigin: string;
+		environmentRef: string;
+		interactionRef: string;
+		planDigest: string;
+		platform: EnvironmentRequest["platform"];
+		architecture: EnvironmentRequest["architecture"];
+		moduleIds: string[];
+		artifactDigest: string;
+		signatureRef: string;
+		resourceLimits: DeviceResourceLimits;
+	} | null;
+}
+export type VisualChallengeAnswer = {
+	type: "TEXT";
+	text: string;
+} | {
+	type: "POINTS";
+	points: {
+		x: number;
+		y: number;
+	}[];
+};
+export interface ConnectionChallenge {
+	challengeRef: string;
+	kind: "VISUAL_TEXT" | "VISUAL_POINTS";
+	maximumAttempts: number;
+	attempts: number;
+}
+export interface ConnectionObservation {
+	observationRef: string;
+	deviceRef: string;
+	resourceRef: string;
+	connectionRef: string;
+	digest: string;
+	capturedAt: string;
+	expiresAt: string;
+	evidenceRef: string;
+	kind: "QR_CODE" | "VISUAL_TEXT" | "VISUAL_POINTS" | "LOGIN" | "NONE";
+	challenge?: ConnectionChallenge;
+	/** 本机登录事实与具体业务账号映射分离；只有原 Human 核对这张准确画面才可完成后者。 */
+	accountConfirmation?: {
+		basis: "HUMAN_REVIEW_REQUIRED";
+		localLogin: "AUTHENTICATED";
+		identity: "OWNER_SELECTED_VIEW" | "NOT_ATTESTED";
+		validUntil: string;
+	};
+}
+export interface AccountConnectionView {
+	protocol: "native-engagement.account-connection/1";
+	tenantId: string;
+	connectionRef: string;
+	interactionRef: string;
+	deviceRef: string;
+	resourceRef: string;
+	profileRef: string;
+	revision: number;
+	state: "APPROVAL_REQUIRED" | "QUEUED" | "RUNNING" | "AUTHENTICATED" | "HUMAN_REQUIRED" | "UNKNOWN" | "BLOCKED" | "CANCELLED";
+	operationRef: string | null;
+	observation: ConnectionObservation | null;
+	blockers: string[];
+	authentication: {
+		observedAt: string;
+		validUntil: string;
+		accountRef: string;
+		basis: "HOST_OBSERVED_ACCOUNT" | "HUMAN_CONFIRMED_LOCAL_ACCOUNT";
+		remoteAuthentication: "NOT_ATTESTED";
+	} | null;
+	approvalExpiresAt: string;
+	online: boolean | null;
+	currentness: "CURRENT" | "EXPIRED" | "NOT_OBSERVED";
+}
+/** 首个账号准备与原连接分离；未有真实广告时不返回 resource、placement 或登录成功。 */
+export type AccountSetupModule = "android.wechat" | "android.whatsapp";
+export interface AccountSetupIntent {
+	setupRef: string;
+	deviceRef: string;
+	moduleId: AccountSetupModule;
+	displayName: string;
+	installationRef?: string;
+	expectedNodeGeneration?: number;
+	expectedFingerprint?: string;
+}
+export interface AccountSetupBinding {
+	tenantId: string;
+	providerRef: string;
+	accountRef: string;
+	profileRef: string;
+	hostRef: string;
+	sessionRef: string;
+	capabilityRef: string;
+}
+export interface AccountSetupView extends AccountSetupIntent {
+	protocol: "native-engagement.account-setup/1";
+	tenantId: string;
+	interactionRef: string;
+	requestDigest: string;
+	revision: number;
+	state: "APPROVAL_REQUIRED" | "AUTHORITY_REQUIRED" | "QUEUED" | "RUNNING" | "LOGIN_REQUIRED" | "RESTART_REQUIRED" | "RESOURCE_READY" | "BLOCKED" | "UNKNOWN";
+	binding: AccountSetupBinding | null;
+	authorityPath: "/desktop/v1/accountsetup";
+	resource: {
+		resourceRef: string;
+		placementRevision: number;
+	} | null;
+	evidence: {
+		evidenceRef: string;
+		digest: string;
+		capturedAt: string;
+		expiresAt: string;
+	} | null;
+	blockers: string[];
+	originalOperationRef: string | null;
+}
 /** 固定的输入错误可在 HTTP/SDK 边界映射，避免把解析细节带进业务错误。 */
 export declare class ContractDiscoveryInputError extends Error {
 	constructor();
@@ -1546,6 +2156,143 @@ export declare class RemoteNativeEngagementSdk {
 	enquiry(payload: Readonly<Record<string, unknown>>): Promise<unknown>;
 	agentStackPreflight(payload: Readonly<Record<string, unknown>>): Promise<unknown>;
 }
+export type WorkClient = Pick<RemoteNativeEngagementSdk, "query" | "command">;
+export interface EngagementInteractionPage {
+	tenantId: string;
+	items: EngagementInteraction[];
+	nextCursor: string | null;
+}
+/** 便携客户端只调用 canonical 入口；未知写入不自动重试，继续使用原幂等键和 interactionRef 查询。 */
+export declare function interactionClient(sdk: WorkClient): {
+	request: (input: InteractionRequestInput) => Promise<EngagementInteraction>;
+	get: (input: InteractionGetInput) => Promise<EngagementInteraction>;
+	list: (input?: InteractionListInput) => Promise<EngagementInteractionPage>;
+	revise: (input: InteractionReviseInput) => Promise<EngagementInteraction>;
+	assign: (input: InteractionAssignInput) => Promise<EngagementInteraction>;
+	respond: (input: InteractionRespondInput) => Promise<EngagementInteraction>;
+	apply: (input: InteractionExpectedInput) => Promise<EngagementInteraction>;
+	cancel: (input: InteractionCancelInput) => Promise<EngagementInteraction>;
+};
+export type InteractionClient = ReturnType<typeof interactionClient>;
+export interface DeviceListInput {
+	limit?: number;
+}
+export interface DevicePage {
+	tenantId: string;
+	items: ExecutionDeviceView[];
+}
+export interface DeviceInspectInput {
+	deviceRef: string;
+}
+export interface EnvironmentGetInput {
+	environmentRef: string;
+}
+export interface EnvironmentEnrollmentInput {
+	idempotencyKey: string;
+	environmentRef: string;
+	interactionRef: string;
+	planDigest: string;
+	installationRef: string;
+	expectedFingerprint: string;
+}
+export interface EnvironmentRequestInput extends Omit<InteractionRequestInput, "operation"> {
+	operation: InteractionEnvironmentInstallation;
+}
+export interface ConnectionRequestInput extends Omit<InteractionRequestInput, "operation"> {
+	operation: InteractionAccountConnection;
+}
+export interface ConnectionGetInput {
+	connectionRef: string;
+}
+export interface ConnectionObserveInput extends ConnectionGetInput {
+	idempotencyKey: string;
+	captureImage: boolean;
+}
+export interface ConnectionEvidenceInput extends ConnectionGetInput {
+	observationRef: string;
+	digest: string;
+}
+export interface ConnectionChallengeInput extends ConnectionEvidenceInput {
+	idempotencyKey: string;
+	challengeRef: string;
+	answer: VisualChallengeAnswer;
+}
+/** 恢复仅允许准确 Human 许可原未知操作后的观察，不重做原答案。 */
+export interface ConnectionRecoverInput extends ConnectionGetInput {
+	idempotencyKey: string;
+	operationRef: string;
+	confirmation: "ORIGINAL_ACCOUNT_REVIEWED";
+}
+/** 仅准确 Human 可把真实本机登录观察和其账号核对结合；不声明服务商远端认证。 */
+export interface ConnectionAccountConfirmInput extends ConnectionEvidenceInput {
+	idempotencyKey: string;
+	expectedRevision: number;
+	confirmation: "VISIBLE_ACCOUNT_MATCHES_PROFILE";
+}
+export interface ConnectionEvidence {
+	connectionRef: string;
+	observationRef: string;
+	digest: string;
+	deviceRef: string;
+	resourceRef: string;
+	capturedAt: string;
+	expiresAt: string;
+	mimeType: "image/png";
+	dataBase64: string;
+}
+/** Device 是已授权原 Node 的摘要；登记、在线和模块可执行状态分别由服务端原事实决定。 */
+export declare function deviceClient(sdk: WorkClient): {
+	list: (input?: DeviceListInput) => Promise<DevicePage>;
+	inspect: (input: DeviceInspectInput) => Promise<ExecutionDeviceView>;
+	requestEnvironment: (input: EnvironmentRequestInput) => Promise<ExecutionEnvironmentView>;
+	environment: (input: EnvironmentGetInput) => Promise<ExecutionEnvironmentView>;
+	attachEnrollment: (input: EnvironmentEnrollmentInput) => Promise<ExecutionEnvironmentView>;
+};
+export declare function connectionClient(sdk: WorkClient): {
+	request: (input: ConnectionRequestInput) => Promise<AccountConnectionView>;
+	get: (input: ConnectionGetInput) => Promise<AccountConnectionView>;
+	observe: (input: ConnectionObserveInput) => Promise<AccountConnectionView>;
+	submitChallenge: (input: ConnectionChallengeInput) => Promise<AccountConnectionView>;
+	recover: (input: ConnectionRecoverInput) => Promise<AccountConnectionView>;
+	confirmAccount: (input: ConnectionAccountConfirmInput) => Promise<AccountConnectionView>;
+	evidence: (input: ConnectionEvidenceInput) => Promise<ConnectionEvidence>;
+};
+export type DeviceClient = ReturnType<typeof deviceClient>;
+export type ConnectionClient = ReturnType<typeof connectionClient>;
+export interface AccountSetupRequestInput extends Omit<InteractionRequestInput, "operation"> {
+	operation: AccountSetupIntent;
+}
+export interface AccountSetupGetInput {
+	setupRef: string;
+}
+export interface AccountSetupObserveInput extends AccountSetupGetInput {
+	idempotencyKey: string;
+}
+export interface AccountSetupEvidenceInput extends AccountSetupGetInput {
+	evidenceRef: string;
+	digest: string;
+}
+export interface AccountSetupRecoveryInput extends AccountSetupObserveInput {
+	originalOperationRef: string;
+}
+export interface AccountSetupEvidence extends AccountSetupEvidenceInput {
+	tenantId: string;
+	capturedAt: string;
+	expiresAt: string;
+	mimeType: "image/png";
+	dataBase64: string;
+}
+/** 便携客户端只保留原件与 canonical schema；不固定 Agent 流程，不自动重试安装或借用 Human 身份。 */
+export declare function accountSetupClient(sdk: WorkClient): {
+	request: (input: AccountSetupRequestInput) => Promise<AccountSetupView>;
+	get: (input: AccountSetupGetInput) => Promise<AccountSetupView>;
+	observe: (input: AccountSetupObserveInput) => Promise<AccountSetupView>;
+	/** 当前 Human 对原 UNKNOWN 只读核对，不能以恢复名义再安装或新建资源。 */
+	recoverHuman: (input: AccountSetupRecoveryInput) => Promise<AccountSetupView>;
+	/** 图像接口只适用于原当前 Human 客户端；业务 MCP Agent 仅取得非秘密引用。 */
+	evidenceHuman: (input: AccountSetupEvidenceInput) => Promise<AccountSetupEvidence>;
+};
+export type AccountSetupClient = ReturnType<typeof accountSetupClient>;
 export declare const MCP_CATALOG_META_KEY = "native-engagement/toolCatalog";
 /** 结构化 MCP 端口不依赖具体客户端包，保持公开 SDK 的便携依赖边界。 */
 export interface McpCatalogClient {
@@ -1583,7 +2330,6 @@ export declare class NativeMcpToolCatalog {
 		content?: readonly unknown[] | undefined;
 	}>;
 }
-export type WorkClient = Pick<RemoteNativeEngagementSdk, "query" | "command">;
 /** Authenticated API parity; the service resolves identity and enforces every contract. */
 export declare function prospectClient(client: WorkClient): {
 	preview: (input: ProspectImportInput) => Promise<ProspectBatchView>;
@@ -1600,6 +2346,57 @@ export declare function prospectClient(client: WorkClient): {
 		cursor?: string;
 	}) => Promise<EngagementCatalogPage>;
 };
+export interface MailSignatureInput {
+	idempotencyKey: string;
+	signatureRef: string;
+	expectedVersion: number;
+	displayName: string;
+	enabled: boolean;
+	text: string;
+	html?: string;
+	inlineImages?: readonly MailSignatureImage[];
+}
+export interface MailDraftInput {
+	idempotencyKey: string;
+	engagementRef: string;
+	conversationRef?: string;
+	messageRef: string;
+	routeRef: string;
+	senderParticipantRef: string;
+	recipientParticipantRef: string;
+	subject: string;
+	text: string;
+	html?: string | null;
+	inlineImages?: readonly {
+		cid: string;
+		assetRef: string;
+	}[];
+	attachments?: readonly MessageAttachmentChoice[];
+	signatureProfileRef?: string | null;
+	replyToMessageRef?: string;
+}
+/** SDK 仅装配正式合同，不接受调用者声明 Tenant 身份、权限或冻结签名内容。 */
+export declare function mailClient(client: WorkClient): {
+	signatures: (input?: {
+		offset?: number;
+		limit?: number;
+	}) => Promise<MailSignaturePage>;
+	signature: (signatureRef: string) => Promise<MailSignatureTemplate>;
+	configureSignature: (input: MailSignatureInput) => Promise<ActionReceipt>;
+	bindSignature: (input: {
+		idempotencyKey: string;
+		profileRef: string;
+		expectedRevision: number;
+		signatureRef: string | null;
+	}) => Promise<ActionReceipt>;
+	draft: ({ profileRef, ...input }: MailDraftInput & {
+		profileRef: string;
+	}) => Promise<ActionReceipt>;
+	revise: (input: MailDraftInput & {
+		expectedVersion: number;
+	}) => Promise<ActionReceipt>;
+	message: (engagementRef: string, messageRef: string) => Promise<EmailMessageProjection>;
+};
 export interface BrowserProfileAccountOwner {
 	readonly profileRef: string;
 	readonly platform: BrowserSocialPlatform;
@@ -1790,4 +2587,8 @@ export declare function createNativePublicLogin(serviceOrigin?: string, fetcher?
 /** Open the authorization page in the operating system browser; never pass a password. */
 export declare function openNativeLoginPage(address: string): Promise<void>;
 
+export {
+	MessageAttachmentChoice as EmailAttachmentChoice,
+};
+
 export {};