@dp-bohrium/widget-sdk 0.8.0 → 0.10.0

package/dist/protocol/generated-runtime-contracts.d.ts

@@ -80,20 +80,6 @@ export type GrantedCapability = ({
         pageSize: number;
         minPollMs: number;
     };
-} | {
-    name: "tasks.list";
-    limits: {
-        callsPerMinute: number;
-        pageSize: number;
-        minPollMs: number;
-    };
-} | {
-    name: "tasks.watch";
-    limits: {
-        callsPerMinute: number;
-        pageSize: number;
-        minPollMs: number;
-    };
 } | {
     name: "ui.state";
     limits: {
@@ -286,19 +272,6 @@ export type CapabilityRequest = ({
         file: FileReference;
         suggestedName: string;
     };
-} | {
-    operation: "tasks.list";
-    input: {
-        cursor?: string;
-        limit?: number;
-    };
-} | {
-    operation: "tasks.watch";
-    input: {
-        taskId: string;
-        cursor?: string;
-        limit?: number;
-    };
 } | {
     operation: "ui.state";
     input: ({
@@ -513,10 +486,6 @@ export type RegionCapabilityResult = ({
     message: string;
     retryable: boolean;
 });
-/**
- * Host 投影给 Widget 的统一任务状态。
- */
-export type TaskStatus = ("queued" | "running" | "succeeded" | "failed" | "cancelled" | "expired");
 /**
  * Host 用户服务标识；固定为 host.user。
  */
@@ -545,6 +514,124 @@ export type HostUserServiceRequest = ({
     action: "email.read";
     payload: HostUserEmailReadInput;
 });
+/**
+ * 受控字段诊断或工程相对源码位置；不携带原始对象。
+ */
+export type WidgetDiagnosticDetail = ({
+    field: string;
+    expected?: string;
+    observed?: string;
+} | {
+    file: string;
+    line: number;
+    column: number;
+    excerpt?: string;
+});
+/**
+ * 保留 transport、HTTP 与非法响应事实；不包含 URL 或原始响应。
+ */
+export type WidgetDiagnosticIO = ({
+    kind: ("transport" | "invalid-response");
+    sourceCode?: string;
+} | {
+    kind: "http";
+    status: number;
+    sourceCode?: string;
+});
+/**
+ * 恢复动作的语义及类型化参数；可信宿主绑定已有工具，不包含任意命令。
+ */
+export type WidgetRecoveryAction = ({
+    id: "inspect";
+    params: {
+        area: ("toolchain" | "host-bridge" | "configuration" | "bundle" | "handshake" | "render" | "capability" | "lease" | "operation-outcome" | "runtime");
+    };
+} | {
+    id: "wait";
+    params: {
+        milestone: ("budget-reset" | "connection-restored");
+        retryAfterMs?: number;
+    };
+} | {
+    id: "edit-project";
+    params: {
+        evidence: "diagnostics";
+    };
+} | {
+    id: "build-project";
+    params: {
+        target: "current-project";
+    };
+} | {
+    id: "refresh-preview";
+    params: {
+        target: "current-project";
+    };
+} | {
+    id: "verify-scenario";
+    params: {
+        target: ("current-attempt" | "next-built-generation");
+        scenarioId?: string;
+    };
+} | {
+    id: "request-external-action";
+    params: {
+        reason: ("authorization" | "host-support" | "host-start" | "credentials");
+    };
+} | {
+    id: "stop-preview";
+    params: {
+        target: "current-preview";
+    };
+});
+/**
+ * 经 offer/connect 显式选择的开发扩展；不授予 capability。
+ */
+export type WidgetDevelopmentExtension = "development-diagnostics-v1";
+/**
+ * 仅表示受管渲染处理器的处理结果，不代表视觉或业务验收。
+ */
+export type WidgetRenderResult = ({
+    requestId: string;
+    revision: number;
+    outcome: ("handled" | "superseded");
+} | {
+    requestId: string;
+    revision: number;
+    outcome: "failed";
+    diagnostic: WidgetRenderFailureDiagnostic;
+});
+/**
+ * 失败处理回执的 SDK 请求诊断；接收方还须匹配当前 requestId。
+ */
+export type WidgetRenderFailureDiagnostic = (WidgetGuestDiagnostic & {
+    correlationId: string;
+    phase?: ("render" | "update");
+});
+/**
+ * Guest 仅声明 SDK 诊断事实，不得冒充 Host 或工具链。
+ */
+export type WidgetGuestDiagnostic = (WidgetDevelopmentDiagnostic & {
+    source: "sdk";
+});
+/**
+ * 扩展 profile 下的 Widget → Host 消息；原 WidgetToHostMessage 不扩展。
+ */
+export type WidgetDevelopmentMessage = (WidgetToHostMessage | WidgetDiagnosticMessage | WidgetRenderResultMessage);
+/**
+ * 经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。
+ */
+export type WidgetDiagnosticMessage = (BridgeEnvelopeBase & {
+    type: "diagnostic";
+    payload: WidgetGuestDiagnostic;
+});
+/**
+ * 经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。
+ */
+export type WidgetRenderResultMessage = (BridgeEnvelopeBase & {
+    type: "render-result";
+    payload: WidgetRenderResult;
+});
 /**
  * Runtime 契约的汇总根容器；仅用于代码生成与符合性校验，不直接对外签发。
  */
@@ -569,12 +656,6 @@ export interface WidgetRuntimeContracts {
     fileDownloadResult?: FileDownloadResult;
     fileReadResult?: FileReadResult;
     fileWriteResult?: FileWriteResult;
-    taskObservationSnapshot?: TaskObservationSnapshot;
-    taskObservationEvent?: TaskObservationEvent;
-    taskObservationBatch?: TaskObservationBatch;
-    taskListField?: TaskListField;
-    taskListItem?: TaskListItem;
-    taskListPage?: TaskListPage;
     toolResultEnvelope?: ToolResultEnvelope;
     uiStateResult?: UiStateResult;
     uiStateWriteResult?: UiStateWriteResult;
@@ -585,6 +666,14 @@ export interface WidgetRuntimeContracts {
     hostUserEmailReadInput?: HostUserEmailReadInput;
     hostUserEmailReadOutput?: HostUserEmailReadOutput;
     hostUserServiceRequest?: HostUserServiceRequest;
+    widgetDevelopmentDiagnostic?: WidgetDevelopmentDiagnostic;
+    widgetRecoveryContext?: WidgetRecoveryContext;
+    widgetRecoveryPlan?: WidgetRecoveryPlan;
+    widgetRecoveryRule?: WidgetRecoveryRule;
+    widgetDevelopmentOffer?: WidgetDevelopmentOffer;
+    widgetDevelopmentConnect?: WidgetDevelopmentConnect;
+    widgetRenderResult?: WidgetRenderResult;
+    widgetDevelopmentMessage?: WidgetDevelopmentMessage;
 }
 /**
  * 渲染请求公共字段：schemaVersion、requestId、instanceId、revision、state、context。
@@ -1095,130 +1184,143 @@ export interface FileWriteResult {
     mutationId: FileMutationId;
 }
 /**
- * 任务观察的当前快照：taskId、status 与 updatedAt；progress、message 可选。
+ * 受限 UI 状态读取结果。
  */
-export interface TaskObservationSnapshot {
-    taskId: string;
-    status: TaskStatus;
-    progress?: number;
-    message?: string;
-    updatedAt: string;
+export interface UiStateResult {
+    found: boolean;
+    value?: JsonValue;
 }
 /**
- * 任务观察流中的单条事件；payload 由服务端裁剪。
+ * 受限 UI 状态写入结果。
  */
-export interface TaskObservationEvent {
-    id: string;
-    type: ("started" | "progress" | "succeeded" | "failed" | "cancelled" | "expired");
-    occurredAt: string;
-    payload: JsonValue;
+export interface UiStateWriteResult {
+    status: "saved";
 }
 /**
- * 任务观察的一页结果：快照 + 有限事件页 + 游标。
+ * 读取用户资料的结果；含稳定 userId 与展示名。
  */
-export interface TaskObservationBatch {
+export interface HostUserProfileReadOutput {
+    userId: string;
+    displayName: string;
+}
+/**
+ * 读取用户邮箱的结果；email 为地址或 null。
+ */
+export interface HostUserEmailReadOutput {
+    email: (string | null);
+}
+/**
+ * 可信出口的标准诊断；恢复指令和 scope 由宿主另行生成。
+ */
+export interface WidgetDevelopmentDiagnostic {
     schemaVersion: 1;
-    taskId: string;
-    cursor: string;
-    reset: boolean;
-    hasMore: boolean;
-    snapshot: TaskObservationSnapshot;
+    source: ("sdk" | "host" | "toolchain");
+    code: string;
+    sourceCode?: string;
+    phase: ("discovery" | "build" | "config" | "load" | "handshake" | "render" | "update" | "capability" | "dispose");
+    sourcePhase?: string;
+    operation: string;
+    severity: ("warning" | "request-error" | "instance-failure");
+    message: string;
+    retryable?: boolean;
+    correlationId?: string;
     /**
-     * @maxItems 100
+     * @maxItems 8
      */
-    events: TaskObservationEvent[];
+    diagnostics?: [] | [WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail];
+    io?: WidgetDiagnosticIO;
 }
 /**
- * 任务列表中的受限展示字段；key 是稳定机器键，value 是 Host 裁剪后的展示文本。
+ * 复用工具执行结果语义的可信恢复上下文；缺失字段表示未知，不能授权重放。
  */
-export interface TaskListField {
-    /**
-     * 展示字段的稳定机器键，例如 machine 或 command。
-     */
-    key: string;
-    /**
-     * Host 完成授权与裁剪后的展示文本。
-     */
-    value: string;
+export interface WidgetRecoveryContext {
+    progress?: WidgetRecoveryProgress;
+    executionState?: ("not_started" | "finished" | "partial" | "unknown");
+    mayHaveExecuted?: boolean;
 }
 /**
- * Host 已授权发现的任务摘要；taskId 是可继续传给 tasks.watch 的不透明引用。
+ * 可信宿主观察到的恢复进展；重复故障无新证据时不能重复同一修复。
  */
-export interface TaskListItem {
-    /**
-     * 可继续传给 tasks.watch 的 Host 不透明任务引用。
-     */
-    taskId: string;
-    /**
-     * 任务来源类型的稳定机器键。
-     */
-    kind: string;
-    /**
-     * 任务的安全展示名称。
-     */
-    name: string;
-    status: TaskStatus;
-    /**
-     * 可选执行进度，取值范围为 0 到 1。
-     */
-    progress?: number;
-    /**
-     * Host 裁剪后的可选状态说明。
-     */
-    message?: string;
-    /**
-     * 任务摘要最后更新时间，使用 UTC ISO 8601 字符串。
-     */
-    updatedAt: string;
-    /**
-     * 任务面板可展示的受限附加字段。
-     *
-     * @maxItems 32
-     */
-    fields: TaskListField[];
+export interface WidgetRecoveryProgress {
+    repeated: boolean;
+    hasNewEvidence: boolean;
 }
 /**
- * Host 已授权任务摘要的一页结果；nextCursor 缺失表示当前页已到末尾。
+ * 可信宿主选择的恢复计划；不能由 Guest 的诊断 payload 指定。
  */
-export interface TaskListPage {
-    /**
-     * 任务列表页结构版本，当前固定为 1。
-     */
+export interface WidgetRecoveryPlan {
+    progress?: WidgetRecoveryProgress;
     schemaVersion: 1;
+    ruleId: string;
+    ruleVersion: number;
+    disposition: ("retry" | "repair" | "inspect" | "external-action" | "stop");
+    nextAction: WidgetRecoveryAction;
+    verification: WidgetRecoveryVerification;
+    guidance: string;
     /**
-     * 当前页中 Host 已授权的任务摘要。
+     * 首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。
      *
-     * @maxItems 100
-     */
-    tasks: TaskListItem[];
-    /**
-     * 下一页的不透明游标；缺失表示当前列表已到末尾。
+     * @maxItems 8
      */
-    nextCursor?: string;
+    followUpActions: [] | [WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction];
 }
 /**
- * 受限 UI 状态读取结果。
+ * 恢复复验目标；下一成功构建须在取得回执后绑定实际产物。
  */
-export interface UiStateResult {
-    found: boolean;
-    value?: JsonValue;
+export interface WidgetRecoveryVerification {
+    target: ("current-attempt" | "next-built-generation" | "original-operation");
+    milestone: ("diagnostics-updated" | "render-handled" | "scenario-passed" | "operation-confirmed");
+    scenarioId?: string;
 }
 /**
- * 受限 UI 状态写入结果。
+ * 公共恢复规则目录条目；空 codes 仅用于显式 unknown 回退。
  */
-export interface UiStateWriteResult {
-    status: "saved";
+export interface WidgetRecoveryRule {
+    id: string;
+    version: number;
+    /**
+     * @minItems 1
+     * @maxItems 3
+     */
+    sources: [("sdk" | "host" | "toolchain")] | [("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain")] | [("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain")];
+    /**
+     * @maxItems 64
+     */
+    codes: string[];
+    disposition: ("retry" | "repair" | "inspect" | "external-action" | "stop");
+    nextAction: WidgetRecoveryAction;
+    verification: WidgetRecoveryVerification;
+    guidance: string;
+    /**
+     * 首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。
+     *
+     * @maxItems 8
+     */
+    followUpActions: [] | [WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction];
 }
 /**
- * 读取用户资料的结果；含稳定 userId 与展示名。
+ * 独立于旧 bootstrap-ready 的支持声明，接收方仍须校验 frame 来源和挂载尝试。
  */
-export interface HostUserProfileReadOutput {
-    userId: string;
-    displayName: string;
+export interface WidgetDevelopmentOffer {
+    type: "widget-bootstrap-offer";
+    protocolVersion: 1;
+    /**
+     * @minItems 1
+     * @maxItems 1
+     */
+    extensions: [WidgetDevelopmentExtension];
 }
 /**
- * 读取用户邮箱的结果；email 为地址或 null。
+ * 仅在收到当前 iframe 合法 offer 后使用的扩展 connect；旧形状保持不变。
  */
-export interface HostUserEmailReadOutput {
-    email: (string | null);
+export interface WidgetDevelopmentConnect {
+    type: "widget-host-connect";
+    protocolVersion: 1;
+    channelId: string;
+    initPayload: InitPayload;
+    /**
+     * @minItems 1
+     * @maxItems 1
+     */
+    extensions: [WidgetDevelopmentExtension];
 }

package/dist/protocol/index.d.ts

@@ -8,9 +8,9 @@ import type { BridgeEnvelopeBase, GrantedCapability, HostToWidgetMessage, Render
  * public surface drift from the canonical contract.
  */
 export type { FallbackBinding, HostServiceAuthorization, HostServiceAuthorizationGranted, HostServiceAuthorizationRequired, LoadableBinding, NetworkAuthority, RuntimeAuthority, WidgetHostRuntimeConfig, WidgetServiceAccess, } from "./generated-host-runtime-config.js";
-export type { ActivationEvents, HostUserPermission, HostUserPermissions, RequestedPresentationCapability, RequestedRegionCapability, StateCapabilityRequest, TasksCapabilityRequest, WidgetContributionConfig, WidgetManifest, } from "./generated-manifest.js";
+export type { ActivationEvents, HostUserPermission, HostUserPermissions, RequestedPresentationCapability, RequestedRegionCapability, StateCapabilityRequest, WidgetContributionConfig, WidgetManifest, } from "./generated-manifest.js";
 export type { WidgetContribution, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, } from "./generated-plugin-manifest.js";
-export type { BridgeEnvelopeBase, CapabilityRequest, CapabilityRequestMessage, CapabilityResult, CapabilityResultMessage, ComputeReviewRequestedPublicWidgetEvent, ComputeReviewRequestedPublicWidgetEventPayload, DisposeMessage, EmptyPublicWidgetEventPayload, ErrorMessage, FileDownloadResult, FileMutationId, FilePreviewContent, FilePreviewRenderRequest, FileReadInput, FileReadResult, FileReference, FileRevision, FileWriteInput, FileWriteResult, FocusBoundaryPresentationCapabilityRequest, GrantedCapability, GrantedPresentationCapability, GrantedRegionCapability, HostToWidgetMessage, HostUserAction, HostUserEmailReadInput, HostUserEmailReadOutput, HostUserProfileReadInput, HostUserProfileReadOutput, HostUserService, HostUserServiceRequest, InitMessage, InitPayload, JsonValue, PanelContent, PanelRenderRequest, PresentationCapabilityOutput, PresentationCapabilityRequest, PresentationCapabilityResult, PublicWidgetEvent, PublicWidgetEventBase, PublicWidgetEventId, PublicWidgetEventOccurredAt, PublicWidgetEventTopic, PublicWidgetSessionId, PublicWidgetWorkflowId, ReadyMessage, RegionCapabilityRequest, RegionCapabilityResult, RenderMessage, RenderRequest, RenderRequestBase, RenderState, ResizeMessage, ResourceBudget, SandboxApprovalRequestedPublicWidgetEvent, SandboxApprovalRequestedPublicWidgetEventPayload, SandboxApprovedPublicWidgetEvent, SandboxApprovedPublicWidgetEventPayload, SandboxDeniedPublicWidgetEvent, TaskListField, TaskListItem, TaskListPage, TaskObservationBatch, TaskObservationEvent, TaskObservationSnapshot, TaskStatus, Theme, ThemeMode, ToolCallPublicWidgetEvent, ToolCallPublicWidgetEventPayload, ToolLifecycleEvent, ToolResultArtifact, ToolResultContent, ToolResultEnvelope, ToolResultMetric, ToolResultNotice, ToolResultProvenance, ToolResultPublicWidgetEvent, ToolResultPublicWidgetEventPayload, ToolResultRenderRequest, UiStateResult, UiStateWriteResult, UserInputRequestedPublicWidgetEvent, UserInputRequestedPublicWidgetEventPayload, WidgetContributionKind, WidgetError, WidgetEvent, WidgetEventBatch, WidgetEventMessage, WidgetLiveEvent, WidgetNetworkFetchInput, WidgetNetworkFetchOutput, WidgetNetworkLimits, WidgetRenderContext, WidgetServicePermission, WidgetServicePermissions, WidgetToHostMessage, WorkflowDonePublicWidgetEvent, WorkflowDonePublicWidgetEventPayload, WorkflowErrorPublicWidgetEvent, WorkflowErrorPublicWidgetEventPayload, WorkflowStartedPublicWidgetEvent, WorkflowStartedPublicWidgetEventPayload, } from "./generated-runtime-contracts.js";
+export type { BridgeEnvelopeBase, CapabilityRequest, CapabilityRequestMessage, CapabilityResult, CapabilityResultMessage, ComputeReviewRequestedPublicWidgetEvent, ComputeReviewRequestedPublicWidgetEventPayload, DisposeMessage, EmptyPublicWidgetEventPayload, ErrorMessage, FileDownloadResult, FileMutationId, FilePreviewContent, FilePreviewRenderRequest, FileReadInput, FileReadResult, FileReference, FileRevision, FileWriteInput, FileWriteResult, FocusBoundaryPresentationCapabilityRequest, GrantedCapability, GrantedPresentationCapability, GrantedRegionCapability, HostToWidgetMessage, HostUserAction, HostUserEmailReadInput, HostUserEmailReadOutput, HostUserProfileReadInput, HostUserProfileReadOutput, HostUserService, HostUserServiceRequest, InitMessage, InitPayload, JsonValue, PanelContent, PanelRenderRequest, PresentationCapabilityOutput, PresentationCapabilityRequest, PresentationCapabilityResult, PublicWidgetEvent, PublicWidgetEventBase, PublicWidgetEventId, PublicWidgetEventOccurredAt, PublicWidgetEventTopic, PublicWidgetSessionId, PublicWidgetWorkflowId, ReadyMessage, RegionCapabilityRequest, RegionCapabilityResult, RenderMessage, RenderRequest, RenderRequestBase, RenderState, ResizeMessage, ResourceBudget, SandboxApprovalRequestedPublicWidgetEvent, SandboxApprovalRequestedPublicWidgetEventPayload, SandboxApprovedPublicWidgetEvent, SandboxApprovedPublicWidgetEventPayload, SandboxDeniedPublicWidgetEvent, Theme, ThemeMode, ToolCallPublicWidgetEvent, ToolCallPublicWidgetEventPayload, ToolLifecycleEvent, ToolResultArtifact, ToolResultContent, ToolResultEnvelope, ToolResultMetric, ToolResultNotice, ToolResultProvenance, ToolResultPublicWidgetEvent, ToolResultPublicWidgetEventPayload, ToolResultRenderRequest, UiStateResult, UiStateWriteResult, UserInputRequestedPublicWidgetEvent, UserInputRequestedPublicWidgetEventPayload, WidgetContributionKind, WidgetError, WidgetEvent, WidgetEventBatch, WidgetEventMessage, WidgetLiveEvent, WidgetNetworkFetchInput, WidgetNetworkFetchOutput, WidgetNetworkLimits, WidgetRenderContext, WidgetServicePermission, WidgetServicePermissions, WidgetToHostMessage, WorkflowDonePublicWidgetEvent, WorkflowDonePublicWidgetEventPayload, WorkflowErrorPublicWidgetEvent, WorkflowErrorPublicWidgetEventPayload, WorkflowStartedPublicWidgetEvent, WorkflowStartedPublicWidgetEventPayload, } from "./generated-runtime-contracts.js";
 export type { WidgetActivationEvent, WidgetActivationEvents, WidgetPluginManifest, WidgetToolPhase, } from "./plugin-manifest.js";
 export { isWidgetActivationEvent, WIDGET_ACTIVATION_EVENTS, } from "./plugin-manifest.js";
 export type { WidgetEventName } from "./widget-events.js";
@@ -41,3 +41,8 @@ export type BridgeEnvelope<TType extends string = string, TPayload = unknown> =
 };
 /** 可加载绑定与降级绑定的联合，即 Host Runtime Config 中一条 binding 的两种结果。 */
 export type ResolvedWidgetBinding = LoadableBinding | FallbackBinding;
+export { isWidgetDevelopmentOffer, isWidgetGuestDiagnostic, isWidgetRenderResult, } from "./development-guards.js";
+export type { WidgetDevelopmentConnect, WidgetDevelopmentDiagnostic, WidgetDevelopmentExtension, WidgetDevelopmentMessage, WidgetDevelopmentOffer, WidgetDiagnosticDetail, WidgetDiagnosticIO, WidgetDiagnosticMessage, WidgetGuestDiagnostic, WidgetRecoveryAction, WidgetRecoveryContext, WidgetRecoveryPlan, WidgetRecoveryProgress, WidgetRecoveryRule, WidgetRecoveryVerification, WidgetRenderResult, WidgetRenderResultMessage, } from "./generated-runtime-contracts.js";
+export { createWidgetRecoveryPlan, findWidgetRecoveryRule, projectWidgetCapabilityDiagnostic, projectWidgetRuntimeDiagnostic, projectWidgetToolchainDiagnostic, selectWidgetDevelopmentExtensions, WIDGET_RECOVERY_RULES, } from "./widget-recovery.js";
+/** SDK 运行层使用的已协商消息；旧 WidgetProtocolMessage 联合保持不变。 */
+export type WidgetRuntimeProtocolMessage = WidgetProtocolMessage | import("./generated-runtime-contracts.js").WidgetDevelopmentMessage;

package/dist/protocol/widget-recovery.d.ts

@@ -0,0 +1,19 @@
+import type { CapabilityResult, WidgetDevelopmentDiagnostic, WidgetDevelopmentExtension, WidgetDevelopmentOffer, WidgetError, WidgetGuestDiagnostic, WidgetRecoveryContext, WidgetRecoveryPlan, WidgetRecoveryRule } from "./generated-runtime-contracts.js";
+/** 包含 unknown 与操作核对规则，Agent 可按 plan.ruleId 定位每个实际计划。 */
+export declare const WIDGET_RECOVERY_RULES: readonly WidgetRecoveryRule[];
+/** 根据稳定码选择通用规则；未知码明确走排查，不匹配自由文本。 */
+export declare function findWidgetRecoveryRule(diagnostic: Pick<WidgetDevelopmentDiagnostic, "source" | "code">): WidgetRecoveryRule;
+/** 纯规则选择，不运行工具；宿主仍须校验实际能力、权限、scope 与恢复预算。 */
+export declare function createWidgetRecoveryPlan(diagnostic: WidgetDevelopmentDiagnostic, context?: WidgetRecoveryContext): WidgetRecoveryPlan;
+/** 只投影已校验的稳定字段；Guest message、context 和恢复文字不进入可信诊断。 */
+export declare function projectWidgetRuntimeDiagnostic(error: WidgetError, operation: string, diagnostics?: WidgetDevelopmentDiagnostic["diagnostics"]): WidgetGuestDiagnostic;
+/** 能力拒绝只影响当前请求；不把它投影为实例终态。 */
+export declare function projectWidgetCapabilityDiagnostic(failure: Extract<CapabilityResult, {
+    ok: false;
+}>, operation: string): WidgetDevelopmentDiagnostic;
+/** 工程错误仅提取稳定 code；原始 stdout/stderr 由可信工具单独脱敏投影。 */
+export declare function projectWidgetToolchainDiagnostic(error: {
+    code: string;
+}, operation: string, phase: "discovery" | "build" | "config"): WidgetDevelopmentDiagnostic;
+/** 仅选择双方声明的扩展；实际 frame 来源和当前 attempt 仍由 Host 校验。 */
+export declare function selectWidgetDevelopmentExtensions(offer: WidgetDevelopmentOffer | undefined, supported: readonly WidgetDevelopmentExtension[]): readonly WidgetDevelopmentExtension[];

package/dist/{protocol-endpoint-CDz-YDGT.js → protocol-endpoint-DbT0OJNu.js}

@@ -1,5 +1,8 @@
+import { n as isWidgetGuestDiagnostic, r as isWidgetRenderResult } from "./development-guards-COvBR0G1.js";
 //#region src/runtime/transport.ts
 const protocolMessageTypes = /* @__PURE__ */ new Set([
+	"diagnostic",
+	"render-result",
 	"init",
 	"render",
 	"update",
@@ -25,6 +28,8 @@ function isFiniteNonNegative(value) {
 }
 function isProtocolPayload(type, payload) {
 	switch (type) {
+		case "diagnostic": return isWidgetGuestDiagnostic(payload);
+		case "render-result": return isWidgetRenderResult(payload);
 		case "init": return hasRequiredKeys(payload, [
 			"instanceId",
 			"locale",

package/dist/runtime/bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RegionCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "../protocol/index.js";
+import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RegionCapabilityResult, RenderRequest, WidgetError, WidgetGuestDiagnostic, WidgetLiveEvent, WidgetRenderResult } from "../protocol/index.js";
 import { type PresentationFocusDirection, type PresentationSurface, type RegionName, type WidgetCapabilityRequestOptions, type WidgetClientEvents, type WidgetClientState } from "./client.js";
 import { type SubscribeWidgetEventsOptions, type WidgetEventSubscription, type WidgetToolHooks } from "./events.js";
 import type { WidgetNetworkClient } from "./network.js";
@@ -109,6 +109,8 @@ export declare class WidgetRuntimeClient {
     private stopPresentationKeyboard;
     dispose(): void;
     private receiveConnection;
+    reportDevelopmentDiagnostic(diagnostic: WidgetGuestDiagnostic): void;
+    reportRenderResult(result: WidgetRenderResult): void;
     private requireClient;
     private removeConnectionListener;
     private failConnection;

package/dist/runtime/client.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RegionCapabilityRequest, RegionCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "../protocol/index.js";
+import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RegionCapabilityRequest, RegionCapabilityResult, RenderRequest, WidgetError, WidgetGuestDiagnostic, WidgetLiveEvent, WidgetRenderResult } from "../protocol/index.js";
 import { type WidgetNetworkClient } from "./network.js";
 import type { WidgetTransport } from "./transport.js";
 export type WidgetClientState = "created" | "waiting-ready" | "ready" | "disposed";
@@ -8,6 +8,7 @@ export interface WidgetClientOptions {
     widgetSdkVersion: string;
     hostApiVersion?: 1;
     initialPayload?: InitPayload;
+    developmentDiagnostics?: boolean;
     handshakeTimeoutMs?: number;
     capabilityTimeoutMs?: number;
     createMessageId?: () => string;
@@ -48,6 +49,7 @@ export declare class WidgetClient {
     private readonly endpoint;
     private readonly widgetSdkVersion;
     private readonly channelId;
+    private readonly developmentDiagnostics;
     private readonly handshakeTimeoutMs;
     private readonly capabilityTimeoutMs;
     private readonly createMessageId;
@@ -81,6 +83,8 @@ export declare class WidgetClient {
     private receive;
     private initialize;
     private initializeAsync;
+    reportDevelopmentDiagnostic(diagnostic: WidgetGuestDiagnostic): void;
+    reportRenderResult(result: WidgetRenderResult): void;
     private send;
     private assertUsable;
     private acceptsRender;

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
-import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-D2xmZVSb.js";
-import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-CDz-YDGT.js";
+import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-Bn_ee8xy.js";
+import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-DbT0OJNu.js";
 export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, REGION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/runtime/protocol-endpoint.d.ts

@@ -1,17 +1,17 @@
-import type { WidgetProtocolMessage } from "../protocol/index.js";
+import type { WidgetRuntimeProtocolMessage } from "../protocol/index.js";
 import { type WidgetTransport } from "./transport.js";
 declare const envelopeFields: readonly ["protocolVersion", "channelId", "messageId", "sequence"];
 type EnvelopeField = (typeof envelopeFields)[number];
-export type ProtocolMessageBody<TMessage extends WidgetProtocolMessage> = TMessage extends WidgetProtocolMessage ? Omit<TMessage, EnvelopeField> : never;
-interface ProtocolEndpointOptions<TInbound extends WidgetProtocolMessage> {
+export type ProtocolMessageBody<TMessage extends WidgetRuntimeProtocolMessage> = TMessage extends WidgetRuntimeProtocolMessage ? Omit<TMessage, EnvelopeField> : never;
+interface ProtocolEndpointOptions<TInbound extends WidgetRuntimeProtocolMessage> {
     transport: WidgetTransport;
     channelId: string;
     createMessageId: () => string;
-    acceptsInbound: (message: WidgetProtocolMessage) => message is TInbound;
+    acceptsInbound: (message: WidgetRuntimeProtocolMessage) => message is TInbound;
     onMessage: (message: TInbound) => void;
     onError?: (error: Error) => void;
 }
-export declare class ProtocolEndpoint<TInbound extends WidgetProtocolMessage, TOutbound extends WidgetProtocolMessage> {
+export declare class ProtocolEndpoint<TInbound extends WidgetRuntimeProtocolMessage, TOutbound extends WidgetRuntimeProtocolMessage> {
     private readonly transport;
     private readonly channelId;
     private readonly createMessageId;

package/dist/runtime/transport.d.ts

@@ -1,7 +1,7 @@
-import type { WidgetProtocolMessage } from "../protocol/index.js";
+import type { WidgetRuntimeProtocolMessage } from "../protocol/index.js";
 export interface WidgetTransport {
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError?(listener: (error: Error) => void): () => void;
     close(): void;
 }
@@ -9,7 +9,7 @@ export interface WidgetTransport {
 export interface WidgetMessagePort {
     onmessage: ((event: MessageEvent<unknown>) => void) | null;
     onmessageerror?: ((event: MessageEvent<unknown>) => void) | null;
-    postMessage(message: WidgetProtocolMessage): void;
+    postMessage(message: WidgetRuntimeProtocolMessage): void;
     start?: () => void;
     close(): void;
 }
@@ -17,14 +17,14 @@ export interface WidgetMessagePort {
  * Performs the inexpensive checks that are possible at the transport edge.
  * Payload-specific validation stays with the contract/conformance layer.
  */
-export declare function isWidgetProtocolMessage(value: unknown): value is WidgetProtocolMessage;
+export declare function isWidgetProtocolMessage(value: unknown): value is WidgetRuntimeProtocolMessage;
 export declare class MemoryTransport implements WidgetTransport {
     private peer?;
     private readonly listeners;
     private closed;
     static pair(): readonly [MemoryTransport, MemoryTransport];
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError(): () => void;
     close(): void;
 }
@@ -35,8 +35,8 @@ export declare class MessagePortTransport implements WidgetTransport {
     private readonly errorListeners;
     private closed;
     constructor(port: WidgetMessagePort);
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError(listener: (error: Error) => void): () => void;
     private reportError;
     close(): void;