@dp-bohrium/widget-sdk 0.5.0 → 0.7.0

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

@@ -0,0 +1,1224 @@
+/** GENERATED FILE. Do not edit directly. */
+/**
+ * Runtime 内部枚举；Forge 外部 Manifest 可声明的 Surface 仅为 file-preview 与 panel。tool-result 仅供受信任的内部 Host、Agent 事件与协议验证，不得作为外部作者 Contribution。
+ */
+export type WidgetContributionKind = ("tool-result" | "file-preview" | "panel");
+/**
+ * 完整渲染请求联合：tool-result（内部）/ file-preview / panel。
+ */
+export type RenderRequest = (ToolResultRenderRequest | FilePreviewRenderRequest | PanelRenderRequest);
+/**
+ * 历史 Host 投影类型；仅供受信任的内部 Host 与协议验证。Forge 新插件不得声明或挂载 tool-result，工具结果应由 Runtime 逻辑映射到自定义 Panel。
+ */
+export type ToolResultRenderRequest = (RenderRequestBase & {
+    contribution: "tool-result";
+    content: ToolResultContent;
+});
+/**
+ * 渲染状态：loading / partial / complete / error。
+ */
+export type RenderState = ("loading" | "partial" | "complete" | "error");
+/**
+ * 主题模式：light 或 dark。
+ */
+export type ThemeMode = ("light" | "dark");
+/**
+ * Host 已授予的能力；多数分支附带调用与预算限制（ui.presentation / ui.region 除外）。
+ */
+export type GrantedCapability = ({
+    name: "service.invoke";
+    services: WidgetServicePermissions;
+    limits: {
+        callsPerMinute: number;
+        requestBytes: number;
+        responseBytes: number;
+    };
+} | {
+    name: "files.list";
+    limits: {
+        pageSize: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.download";
+    limits: {
+        bytesPerRun: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.metadata";
+    limits: {
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.read";
+    limits: {
+        bytesPerRequest: number;
+        /**
+         * @deprecated
+         * 历史读取累计额度字段，仅为兼容旧配置保留；当前 files.read 不累计或执行此额度，新宿主不再下发。
+         */
+        bytesPerRun?: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.write";
+    limits: {
+        bytesPerRequest: number;
+        bytesPerRun: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "events.read";
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    topics: [string, ...(string)[]];
+    limits: {
+        callsPerMinute: number;
+        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: {
+        callsPerMinute: number;
+        bytesPerRun: number;
+        maxValueBytes: number;
+    };
+} | {
+    name: "actions.invoke";
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    actions: [string, ...(string)[]];
+    limits: {
+        callsPerMinute: number;
+    };
+} | {
+    name: "network.fetch";
+    limits: WidgetNetworkLimits;
+} | GrantedPresentationCapability | GrantedRegionCapability);
+/**
+ * 服务权限列表。
+ *
+ * @minItems 1
+ * @maxItems 32
+ */
+export type WidgetServicePermissions = [WidgetServicePermission, ...(WidgetServicePermission)[]];
+/**
+ * 正整数。
+ */
+export type PositiveInteger = number;
+/**
+ * 可序列化为 JSON 的任意值；null / boolean / number / string / 数组 / 对象的递归联合。
+ */
+export type JsonValue = (null | boolean | number | string | JsonValue[] | {
+    [k: string]: JsonValue;
+});
+/**
+ * 文件预览渲染请求：公共字段 + contribution=file-preview + content。
+ */
+export type FilePreviewRenderRequest = (RenderRequestBase & {
+    contribution: "file-preview";
+    content: FilePreviewContent;
+});
+/**
+ * 由存储执行端签发的文件内容版本，用于条件读取和保存；不是 RenderRequest.revision。
+ */
+export type FileRevision = string;
+/**
+ * 面板渲染请求：公共字段 + contribution=panel + content。
+ */
+export type PanelRenderRequest = (RenderRequestBase & {
+    contribution: "panel";
+    content: PanelContent;
+});
+/**
+ * Host → Widget 的 Bridge 消息联合。
+ */
+export type HostToWidgetMessage = (InitMessage | RenderMessage | WidgetEventMessage | CapabilityResultMessage | ErrorMessage | DisposeMessage);
+/**
+ * Host 下发初始上下文的 Bridge 消息。
+ */
+export type InitMessage = (BridgeEnvelopeBase & {
+    type: "init";
+    payload: InitPayload;
+});
+/**
+ * Host 下发完整渲染快照的 Bridge 消息；type 为 render 或 update。
+ */
+export type RenderMessage = (BridgeEnvelopeBase & {
+    type: ("render" | "update");
+    payload: RenderRequest;
+});
+/**
+ * Host 通过当前 Widget MessageChannel 主动推送的 Workflow 事件。
+ */
+export type WidgetEventMessage = (BridgeEnvelopeBase & {
+    type: "event";
+    payload: WidgetLiveEvent;
+});
+/**
+ * 已激活 Widget 可监听的实时事件；session.start 只用于激活，不在此列。
+ */
+export type WidgetEventName = ("turn-start" | "turn-end" | "step-start" | "step-end" | "tool-call-generating" | "tool-call-waiting" | "tool-call-running" | "tool-call-result" | "tool-call-error" | "workspace-file-changed" | "workspace-tree-refresh" | "workspace-file-opened" | "ui-tool-opened" | "ui-panel-focused" | "host-surface-changed");
+/**
+ * Host 返回能力请求结果的 Bridge 消息。
+ */
+export type CapabilityResultMessage = (BridgeEnvelopeBase & {
+    type: "capability-result";
+    payload: {
+        requestId: string;
+        result: CapabilityResult;
+    };
+});
+/**
+ * 能力请求结果：成功时带 data，失败时带 reason / message / retryable。
+ */
+export type CapabilityResult = ({
+    ok: true;
+    data: JsonValue;
+} | {
+    ok: false;
+    reason: ("unsupported" | "permission-denied" | "resource-limit" | "invalid-reference" | "timeout" | "internal-error" | "network-consent-denied" | "network-policy-denied" | "network-transport-unavailable" | "network-request-too-large" | "network-response-too-large" | "network-rate-limited" | "network-redirect-denied" | "network-credential-unavailable" | "network-scope-invalid" | "network-dns-denied" | "network-error" | "revision-conflict" | "mutation-conflict" | "write-outcome-unknown");
+    message: string;
+    retryable: boolean;
+});
+/**
+ * 任一方向的结构化错误 Bridge 消息。
+ */
+export type ErrorMessage = (BridgeEnvelopeBase & {
+    type: "error";
+    payload: WidgetError;
+});
+/**
+ * Host 通知销毁实例的终态 Bridge 消息。
+ */
+export type DisposeMessage = (BridgeEnvelopeBase & {
+    type: "dispose";
+    payload: {
+        reason: string;
+        deadlineMs: number;
+    };
+});
+/**
+ * Widget → Host 的 Bridge 消息联合。
+ */
+export type WidgetToHostMessage = (ReadyMessage | ResizeMessage | CapabilityRequestMessage | ErrorMessage);
+/**
+ * Widget 向 Host 上报就绪的 Bridge 消息；含 SDK 与 Host API 版本。
+ */
+export type ReadyMessage = (BridgeEnvelopeBase & {
+    type: "ready";
+    payload: {
+        widgetSdkVersion: string;
+        hostApiVersion: 1;
+    };
+});
+/**
+ * Widget 请求调整视口尺寸的 Bridge 消息。
+ */
+export type ResizeMessage = (BridgeEnvelopeBase & {
+    type: "resize";
+    payload: {
+        width: number;
+        height: number;
+    };
+});
+/**
+ * Widget 发起能力请求的 Bridge 消息。
+ */
+export type CapabilityRequestMessage = (BridgeEnvelopeBase & {
+    type: "capability-request";
+    payload: {
+        requestId: string;
+        request: CapabilityRequest;
+    };
+});
+/**
+ * Widget 发起的能力请求；以 operation 判别语义与 input。
+ */
+export type CapabilityRequest = ({
+    operation: "service.invoke";
+    input: {
+        service: string;
+        action: string;
+        payload: JsonValue;
+    };
+} | {
+    operation: "files.list";
+    input: {
+        directory: FileReference;
+        cursor?: string;
+        limit?: number;
+    };
+} | {
+    operation: "files.metadata";
+    input: {
+        reference: FileReference;
+    };
+} | {
+    operation: "files.read";
+    input: FileReadInput;
+} | {
+    operation: "files.write";
+    input: FileWriteInput;
+} | {
+    operation: "files.download";
+    input: {
+        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: ({
+        action: "read";
+        key: string;
+    } | {
+        action: "write";
+        key: string;
+        value: JsonValue;
+    });
+} | {
+    operation: "events.read";
+    input: {
+        topic: string;
+        cursor?: string;
+        limit: number;
+    };
+} | {
+    operation: "actions.invoke";
+    input: {
+        action: string;
+        idempotencyKey: string;
+        arguments: JsonValue;
+    };
+} | {
+    operation: "network.fetch";
+    input: WidgetNetworkFetchInput;
+} | PresentationCapabilityRequest | RegionCapabilityRequest);
+/**
+ * 一次逻辑保存的稳定标识；重试或确认结果时必须复用，相同标识不得提交不同内容。
+ */
+export type FileMutationId = string;
+/**
+ * 呈现能力请求：present / change-surface、close，或 focus-boundary。
+ */
+export type PresentationCapabilityRequest = ({
+    operation: "ui.presentation";
+    input: ({
+        action: ("present" | "change-surface");
+        surface: ("workspace" | "floating" | "overlay");
+    } | {
+        action: "close";
+    });
+} | FocusBoundaryPresentationCapabilityRequest);
+/**
+ * 呈现焦点边界请求：forward 或 backward。
+ */
+export type FocusBoundaryPresentationCapabilityRequest = {
+    operation: "ui.presentation";
+    input: {
+        action: "focus-boundary";
+        direction: ("forward" | "backward");
+    };
+};
+/**
+ * 区域能力请求：acquire 或 release。
+ */
+export type RegionCapabilityRequest = ({
+    operation: "ui.region";
+    input: {
+        action: "acquire";
+        region: "session.rightRail";
+    };
+} | {
+    operation: "ui.region";
+    input: {
+        action: "release";
+    };
+});
+/**
+ * Agent Widget 从已解析 Workflow 事件构造并向 Widget Runtime 推送的事件联合。
+ */
+export type PublicWidgetEvent = (WorkflowStartedPublicWidgetEvent | WorkflowDonePublicWidgetEvent | WorkflowErrorPublicWidgetEvent | ToolCallPublicWidgetEvent | ToolResultPublicWidgetEvent | SandboxApprovalRequestedPublicWidgetEvent | SandboxApprovedPublicWidgetEvent | SandboxDeniedPublicWidgetEvent | UserInputRequestedPublicWidgetEvent | ComputeReviewRequestedPublicWidgetEvent);
+/**
+ * Workflow 流建立事件。
+ */
+export type WorkflowStartedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "workflow.lifecycle";
+    type: "connected";
+    payload: WorkflowStartedPublicWidgetEventPayload;
+});
+/**
+ * 用于同一 Agent Widget Runtime 内去重的稳定事件标识。
+ */
+export type PublicWidgetEventId = string;
+/**
+ * 事件产生时间：YYYY-MM-DD + T + 非空格字符，以 Z 结尾。
+ */
+export type PublicWidgetEventOccurredAt = string;
+/**
+ * 事件所属的 Session 标识。
+ */
+export type PublicWidgetSessionId = string;
+/**
+ * 事件所属的 Workflow 标识。
+ */
+export type PublicWidgetWorkflowId = string;
+/**
+ * Workflow 正常终态事件。
+ */
+export type WorkflowDonePublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "workflow.lifecycle";
+    type: "done";
+    payload: WorkflowDonePublicWidgetEventPayload;
+});
+/**
+ * Workflow 错误事件。
+ */
+export type WorkflowErrorPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "workflow.lifecycle";
+    type: "error";
+    payload: WorkflowErrorPublicWidgetEventPayload;
+});
+/**
+ * tool-call 事件。
+ */
+export type ToolCallPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "tools.lifecycle";
+    type: "tool-call";
+    payload: ToolCallPublicWidgetEventPayload;
+});
+/**
+ * tool-result 事件。
+ */
+export type ToolResultPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "tools.lifecycle";
+    type: "tool-result";
+    payload: ToolResultPublicWidgetEventPayload;
+});
+/**
+ * sandbox-approval-requested 事件。
+ */
+export type SandboxApprovalRequestedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "approval.lifecycle";
+    type: "sandbox-approval-requested";
+    payload: SandboxApprovalRequestedPublicWidgetEventPayload;
+});
+/**
+ * sandbox-approved 事件。
+ */
+export type SandboxApprovedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "approval.lifecycle";
+    type: "sandbox-approved";
+    payload: SandboxApprovedPublicWidgetEventPayload;
+});
+/**
+ * sandbox-denied 事件。
+ */
+export type SandboxDeniedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "approval.lifecycle";
+    type: "sandbox-denied";
+    payload: EmptyPublicWidgetEventPayload;
+});
+/**
+ * user-input-requested 事件。
+ */
+export type UserInputRequestedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "interaction.lifecycle";
+    type: "user-input-requested";
+    payload: UserInputRequestedPublicWidgetEventPayload;
+});
+/**
+ * compute-review-requested 事件。
+ */
+export type ComputeReviewRequestedPublicWidgetEvent = (PublicWidgetEventBase & {
+    topic: "interaction.lifecycle";
+    type: "compute-review-requested";
+    payload: ComputeReviewRequestedPublicWidgetEventPayload;
+});
+/**
+ * Agent Widget 从当前 Workflow 流公开的事件主题。
+ */
+export type PublicWidgetEventTopic = ("workflow.lifecycle" | "tools.lifecycle" | "approval.lifecycle" | "interaction.lifecycle");
+/**
+ * 呈现能力输出：present / change-surface / focus-boundary / close。
+ */
+export type PresentationCapabilityOutput = ({
+    action: ("present" | "change-surface");
+    surface: ("workspace" | "floating" | "overlay");
+} | {
+    action: "close";
+} | {
+    action: "focus-boundary";
+    direction: ("forward" | "backward");
+});
+/**
+ * 呈现能力请求的结果。
+ */
+export type PresentationCapabilityResult = ({
+    ok: true;
+    data: PresentationCapabilityOutput;
+} | {
+    ok: false;
+    reason: ("unsupported" | "permission-denied" | "resource-limit" | "invalid-reference" | "timeout" | "internal-error" | "network-consent-denied" | "network-policy-denied" | "network-transport-unavailable" | "network-request-too-large" | "network-response-too-large" | "network-rate-limited" | "network-redirect-denied" | "network-credential-unavailable" | "network-scope-invalid" | "network-dns-denied" | "network-error");
+    message: string;
+    retryable: boolean;
+});
+/**
+ * 区域能力请求的结果；成功时含不透明 leaseId。
+ */
+export type RegionCapabilityResult = ({
+    ok: true;
+    data: {
+        action: ("acquire" | "release");
+        region: "session.rightRail";
+        mode: "replace";
+        leaseId?: string;
+    };
+} | {
+    ok: false;
+    reason: ("unsupported" | "permission-denied" | "resource-limit" | "invalid-reference" | "timeout" | "internal-error");
+    message: string;
+    retryable: boolean;
+});
+/**
+ * Host 投影给 Widget 的统一任务状态。
+ */
+export type TaskStatus = ("queued" | "running" | "succeeded" | "failed" | "cancelled" | "expired");
+/**
+ * Host 用户服务标识；固定为 host.user。
+ */
+export type HostUserService = "host.user";
+/**
+ * Host 用户服务下的具体动作：个人资料或邮箱读取。
+ */
+export type HostUserAction = ("profile.read" | "email.read");
+/**
+ * 读取用户资料的请求输入；当前无需额外参数（null）。
+ */
+export type HostUserProfileReadInput = null;
+/**
+ * 读取用户邮箱的请求输入；当前无需额外参数（null）。
+ */
+export type HostUserEmailReadInput = null;
+/**
+ * Host 用户服务请求；以 action 判别资料或邮箱读取。
+ */
+export type HostUserServiceRequest = ({
+    service: HostUserService;
+    action: "profile.read";
+    payload: HostUserProfileReadInput;
+} | {
+    service: HostUserService;
+    action: "email.read";
+    payload: HostUserEmailReadInput;
+});
+/**
+ * Runtime 契约的汇总根容器；仅用于代码生成与符合性校验，不直接对外签发。
+ */
+export interface WidgetRuntimeContracts {
+    widgetContributionKind: WidgetContributionKind;
+    renderRequest: RenderRequest;
+    hostToWidgetMessage: HostToWidgetMessage;
+    widgetToHostMessage: WidgetToHostMessage;
+    capabilityRequest: CapabilityRequest;
+    capabilityResult: CapabilityResult;
+    widgetError: WidgetError;
+    resourceBudget: ResourceBudget;
+    widgetEventBatch?: WidgetEventBatch;
+    toolLifecycleEvent?: ToolLifecycleEvent;
+    publicWidgetEvent?: PublicWidgetEvent;
+    widgetLiveEvent?: WidgetLiveEvent;
+    publicWidgetEventTopic?: PublicWidgetEventTopic;
+    widgetNetworkFetchOutput?: WidgetNetworkFetchOutput;
+    presentationCapabilityOutput?: PresentationCapabilityOutput;
+    presentationCapabilityResult?: PresentationCapabilityResult;
+    regionCapabilityResult?: RegionCapabilityResult;
+    fileDownloadResult?: FileDownloadResult;
+    fileReadResult?: FileReadResult;
+    fileWriteResult?: FileWriteResult;
+    taskObservationSnapshot?: TaskObservationSnapshot;
+    taskObservationEvent?: TaskObservationEvent;
+    taskObservationBatch?: TaskObservationBatch;
+    taskListField?: TaskListField;
+    taskListItem?: TaskListItem;
+    taskListPage?: TaskListPage;
+    toolResultEnvelope?: ToolResultEnvelope;
+    uiStateResult?: UiStateResult;
+    uiStateWriteResult?: UiStateWriteResult;
+    hostUserService?: HostUserService;
+    hostUserAction?: HostUserAction;
+    hostUserProfileReadInput?: HostUserProfileReadInput;
+    hostUserProfileReadOutput?: HostUserProfileReadOutput;
+    hostUserEmailReadInput?: HostUserEmailReadInput;
+    hostUserEmailReadOutput?: HostUserEmailReadOutput;
+    hostUserServiceRequest?: HostUserServiceRequest;
+}
+/**
+ * 渲染请求公共字段：schemaVersion、requestId、instanceId、revision、state、context。
+ */
+export interface RenderRequestBase {
+    schemaVersion: 1;
+    requestId: string;
+    instanceId: string;
+    revision: number;
+    state: RenderState;
+    context: WidgetRenderContext;
+}
+/**
+ * 渲染上下文：locale、theme、viewport、能力与关联 id。
+ */
+export interface WidgetRenderContext {
+    locale: string;
+    theme: Theme;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    capabilities: GrantedCapability[];
+    correlationId: string;
+}
+/**
+ * 渲染上下文中的主题：mode 与设计令牌表。
+ */
+export interface Theme {
+    mode: ThemeMode;
+    tokens: {
+        background: string;
+        foreground: string;
+        muted: string;
+        mutedForeground: string;
+        border: string;
+        primary: string;
+        danger: string;
+    };
+}
+/**
+ * 单条服务权限：服务名 + 允许的动作列表。
+ */
+export interface WidgetServicePermission {
+    service: string;
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    actions: [string, ...(string)[]];
+}
+/**
+ * Host 托管网络的限制项：超时、并发、频率与字节数。
+ */
+export interface WidgetNetworkLimits {
+    timeoutMs: PositiveInteger;
+    maxRedirects: PositiveInteger;
+    maxConcurrentRequests: PositiveInteger;
+    callsPerMinute: PositiveInteger;
+    requestHeaderBytes: PositiveInteger;
+    responseHeaderBytes: PositiveInteger;
+    requestBodyBytes: PositiveInteger;
+    responseBodyBytes: PositiveInteger;
+}
+/**
+ * 已授予的呈现能力；含 surfaces，requiresHostConfirmation 恒为 true。
+ */
+export interface GrantedPresentationCapability {
+    name: "ui.presentation";
+    /**
+     * @minItems 1
+     * @maxItems 2
+     */
+    surfaces: [("floating" | "overlay")] | [("floating" | "overlay"), ("floating" | "overlay")];
+    requiresHostConfirmation: true;
+}
+/**
+ * 已授予的会话右侧区域替换能力。
+ */
+export interface GrantedRegionCapability {
+    name: "ui.region";
+    /**
+     * @minItems 1
+     * @maxItems 1
+     */
+    regions: ["session.rightRail"];
+    mode: "replace";
+    requiresHostConfirmation: true;
+}
+/**
+ * tool-result 渲染内容；仅内部通道使用，外部作者不挂载。
+ */
+export interface ToolResultContent {
+    contribution: "tool-result";
+    tool: {
+        name: string;
+        callId: string;
+        status: ("running" | "succeeded" | "failed" | "cancelled");
+    };
+    input: JsonValue;
+    result?: JsonValue;
+    envelope?: ToolResultEnvelope;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * 工具执行结果信封；仅供受信任的内部 Host 与 Agent 事件，不进入作者 Contribution。
+ */
+export interface ToolResultEnvelope {
+    schemaVersion: 1;
+    status: ("running" | "succeeded" | "failed" | "cancelled");
+    summary?: string;
+    data?: JsonValue;
+    /**
+     * @maxItems 64
+     */
+    metrics?: ToolResultMetric[];
+    /**
+     * @maxItems 64
+     */
+    artifacts?: ToolResultArtifact[];
+    /**
+     * @maxItems 32
+     */
+    provenance?: ToolResultProvenance[];
+    /**
+     * @maxItems 32
+     */
+    warnings?: ToolResultNotice[];
+    /**
+     * @maxItems 32
+     */
+    missing?: ToolResultNotice[];
+}
+/**
+ * 工具结果中的单个指标。
+ */
+export interface ToolResultMetric {
+    name: string;
+    value: number;
+    unit?: string;
+    label?: string;
+}
+/**
+ * 工具结果中的产物元数据，不含内容本身。
+ */
+export interface ToolResultArtifact {
+    id: string;
+    name: string;
+    kind?: ("file" | "directory");
+    mimeType?: string;
+    size?: number;
+    downloadable?: boolean;
+}
+/**
+ * 工具结果的来源信息。
+ */
+export interface ToolResultProvenance {
+    source: string;
+    kind?: string;
+    label?: string;
+}
+/**
+ * 工具结果中的提示或警告。
+ */
+export interface ToolResultNotice {
+    code: string;
+    message: string;
+}
+/**
+ * 文件预览内容；contribution 必须为 file-preview。
+ */
+export interface FilePreviewContent {
+    contribution: "file-preview";
+    file: FileReference;
+    preview?: JsonValue;
+}
+/**
+ * Host 签发的文件引用；仅含不透明 id、可选内容版本和展示元数据。引用本身不授予写权限，不含路径或 URL。
+ */
+export interface FileReference {
+    id: string;
+    kind: ("file" | "directory");
+    name: string;
+    extension?: string;
+    mimeType?: string;
+    size?: number;
+    revision?: FileRevision;
+}
+/**
+ * 面板内容；contribution 必须为 panel。
+ */
+export interface PanelContent {
+    contribution: "panel";
+    id: string;
+    title?: string;
+    data: JsonValue;
+}
+/**
+ * Bridge 信封公共字段：protocolVersion、channelId、messageId、sequence。
+ */
+export interface BridgeEnvelopeBase {
+    protocolVersion: 1;
+    channelId: string;
+    messageId: string;
+    sequence: number;
+}
+/**
+ * init 消息负载：实例、locale、theme、能力与资源预算。
+ */
+export interface InitPayload {
+    instanceId: string;
+    locale: string;
+    theme: Theme;
+    capabilities: GrantedCapability[];
+    resourceBudget: ResourceBudget;
+}
+/**
+ * Host 为当前运行签发的资源预算：包、Bridge、文件、超时、并发、重试与失败。
+ */
+export interface ResourceBudget {
+    version: 1;
+    bundle: {
+        compressedBytes: number;
+        expandedBytes: number;
+        fileCount: number;
+        singleFileBytes: number;
+    };
+    bridge: {
+        messageBytes: number;
+        messagesPerSecond: number;
+        pendingRequests: number;
+    };
+    files: {
+        readBytesPerRequest: number;
+        /**
+         * @deprecated
+         * 历史读取累计额度字段，仅为兼容旧配置保留；当前 files.read 不累计或执行此额度，新宿主不再下发。
+         */
+        readBytesPerRun?: number;
+        callsPerMinute: number;
+        listPageSize: number;
+        /**
+         * 写入单次原始字节上限；未签发时不得授权 files.write。
+         */
+        writeBytesPerRequest?: number;
+        /**
+         * 当前运行的累计写入原始字节上限；未签发时不得授权 files.write。
+         */
+        writeBytesPerRun?: number;
+    };
+    timeouts: {
+        bundleLoadMs: number;
+        handshakeMs: number;
+        firstRenderMs: number;
+        updateMs: number;
+        capabilityMs: number;
+        disposeGraceMs: number;
+    };
+    concurrency: {
+        activeIframesPerPage: number;
+        activeIframesPerRun: number;
+        hiddenRecycleMs: number;
+    };
+    retry: {
+        maxAttempts: number;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        totalMs: number;
+    };
+    failure: {
+        consecutiveFailures: number;
+        windowMs: number;
+    };
+}
+/**
+ * Host 从当前 Runtime 向 iframe 主动推送的聚合事件；事件由 type 唯一标识。
+ */
+export interface WidgetLiveEvent {
+    type: WidgetEventName;
+    payload: {
+        [k: string]: JsonValue;
+    };
+}
+/**
+ * 结构化稳定错误：code + phase + message + retryable + correlationId。
+ */
+export interface WidgetError {
+    code: ("BUNDLE_LOAD_FAILED" | "DIGEST_MISMATCH" | "RUNTIME_CONFIG_EXPIRED" | "WIDGET_VERSION_REVOKED" | "HOST_API_UNSUPPORTED" | "HANDSHAKE_TIMEOUT" | "MESSAGE_INVALID" | "CHANNEL_MISMATCH" | "MESSAGE_TOO_LARGE" | "MESSAGE_RATE_LIMITED" | "TOO_MANY_PENDING_REQUESTS" | "CAPABILITY_UNDECLARED" | "CAPABILITY_DENIED" | "CAPABILITY_UNSUPPORTED" | "CAPABILITY_TIMEOUT" | "FILE_REFERENCE_INVALID" | "FILE_PERMISSION_DENIED" | "RESOURCE_LIMIT" | "RENDER_FAILED" | "UPDATE_FAILED" | "WIDGET_CRASHED" | "INSTANCE_DISPOSED");
+    phase: ("load" | "handshake" | "render" | "update" | "capability" | "dispose");
+    message: string;
+    retryable: boolean;
+    correlationId: string;
+}
+/**
+ * 分块读取已授权文件；后续分块应携带首块返回的 expectedRevision，防止拼接不同版本。
+ */
+export interface FileReadInput {
+    file: FileReference;
+    offset: number;
+    length: number;
+    encoding: ("utf8" | "base64");
+    expectedRevision?: FileRevision;
+}
+/**
+ * 按 Host 授权范围对已有文件作整文件条件替换；Host 校验引用、作用域、权限和实际字节预算。超时不表示未写入，使用同一 mutationId 核对结果。
+ */
+export interface FileWriteInput {
+    file: FileReference;
+    content: string;
+    encoding: ("utf8" | "base64");
+    expectedRevision: FileRevision;
+    mutationId: FileMutationId;
+}
+/**
+ * Host 托管网络请求输入；url 由 Host 校验，auth 声明凭据需求。
+ */
+export interface WidgetNetworkFetchInput {
+    url: string;
+    auth: ("none" | "optional" | "required");
+    method?: ("GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE");
+    headers?: WidgetNetworkRequestHeaders;
+    body?: string;
+    bodyEncoding?: ("utf8" | "base64");
+    redirect?: ("follow" | "manual" | "error");
+}
+/**
+ * Widget 发起网络请求时附加的请求头集合。
+ */
+export interface WidgetNetworkRequestHeaders {
+    [k: string]: string;
+}
+/**
+ * 低层 events.read 的一页事件：topic、cursor、reset、hasMore 与事件列表。
+ */
+export interface WidgetEventBatch {
+    schemaVersion: 1;
+    topic: string;
+    cursor: string;
+    reset: boolean;
+    hasMore: boolean;
+    /**
+     * @maxItems 100
+     */
+    events: WidgetEvent[];
+    snapshot?: JsonValue;
+}
+/**
+ * 低层 events.read 事件页中的单条原始事件；type 为受限标识、payload 为 JSON。
+ */
+export interface WidgetEvent {
+    id: string;
+    type: string;
+    payload: JsonValue;
+}
+/**
+ * 工具生命周期事件：started / completed / failed / cancelled。
+ */
+export interface ToolLifecycleEvent {
+    toolCallId: string;
+    toolName: string;
+    phase: ("started" | "completed" | "failed" | "cancelled");
+}
+/**
+ * 公开事件公共字段：schemaVersion、id、occurredAt、sessionId、workflowId。
+ */
+export interface PublicWidgetEventBase {
+    schemaVersion: 1;
+    id: PublicWidgetEventId;
+    occurredAt: PublicWidgetEventOccurredAt;
+    sessionId: PublicWidgetSessionId;
+    workflowId: PublicWidgetWorkflowId;
+}
+/**
+ * Workflow 流已建立时公开的数据。
+ */
+export interface WorkflowStartedPublicWidgetEventPayload {
+    protocolVersion: number;
+}
+/**
+ * Workflow 正常结束时公开的数据。
+ */
+export interface WorkflowDonePublicWidgetEventPayload {
+    status: ("completed" | "failed" | "cancelled" | "expired");
+    durationMs?: number;
+    error?: string;
+}
+/**
+ * Workflow 错误事件公开的数据。
+ */
+export interface WorkflowErrorPublicWidgetEventPayload {
+    terminal: boolean;
+    error?: string;
+}
+/**
+ * tool-call 原始语义对应的公开数据。
+ */
+export interface ToolCallPublicWidgetEventPayload {
+    toolCallId: string;
+    toolName: string;
+    args?: JsonValue;
+    executionState?: ("waiting" | "running");
+}
+/**
+ * tool-result 原始语义对应的公开数据。
+ */
+export interface ToolResultPublicWidgetEventPayload {
+    toolCallId: string;
+    toolName?: string;
+    output: JsonValue;
+    durationMs?: number;
+}
+/**
+ * 沙盒审批请求公开的数据。
+ */
+export interface SandboxApprovalRequestedPublicWidgetEventPayload {
+    approvalId: string;
+    mode: ("create" | "reuse");
+    sandboxName?: string;
+    resource?: JsonValue;
+    existingSandboxes?: {
+        id: string;
+        name: string;
+    }[];
+    proxyAgentName?: string;
+}
+/**
+ * 沙盒审批通过时公开的数据。
+ */
+export interface SandboxApprovedPublicWidgetEventPayload {
+    sandboxId: string;
+}
+/**
+ * 没有额外业务字段的事件负载。
+ */
+export interface EmptyPublicWidgetEventPayload {
+}
+/**
+ * 用户输入请求公开的数据。
+ */
+export interface UserInputRequestedPublicWidgetEventPayload {
+    toolCallId?: string;
+    requestId?: string;
+    request?: JsonValue;
+    schema?: JsonValue;
+    title?: string;
+    description?: string;
+    retryAttempt?: number;
+    retryMessage?: string;
+    cancellable?: boolean;
+    timeoutSeconds?: number;
+    proxyWorkflowId?: string;
+    proxyAgentName?: string;
+}
+/**
+ * 计算任务审批请求公开的数据。
+ */
+export interface ComputeReviewRequestedPublicWidgetEventPayload {
+    draftId: string;
+    toolCallId: string;
+}
+/**
+ * Host 托管网络请求结果；body 按 bodyEncoding 解释。
+ */
+export interface WidgetNetworkFetchOutput {
+    status: number;
+    statusText: string;
+    headers: NetworkHeaders;
+    body: string;
+    bodyEncoding: ("utf8" | "base64");
+    finalUrl: string;
+    redirected: boolean;
+}
+/**
+ * HTTP 响应头集合。
+ */
+export interface NetworkHeaders {
+    [k: string]: string;
+}
+/**
+ * 文件下载保存意图的结果：saved / started / cancelled。
+ */
+export interface FileDownloadResult {
+    status: ("saved" | "started" | "cancelled");
+}
+/**
+ * 文件读取结果；普通读取只要求内容与编码，原有游标和截断信息按 Host 能力返回。revision 可选且必须与本次读取的内容属于同一快照；请求 expectedRevision 时必须返回匹配版本。缺少 revision 的结果仅用于只读展示，不能据此条件保存。提供字节游标时 nextOffset 等于请求 offset + bytesRead，不按字符串长度计数。
+ */
+export interface FileReadResult {
+    content: string;
+    encoding: ("utf8" | "base64");
+    offset?: number;
+    bytesRead?: number;
+    nextOffset?: number;
+    eof?: boolean;
+    truncated?: boolean;
+    revision?: FileRevision;
+}
+/**
+ * 执行端已确认持久化的保存回执；file.id 保持原文件引用身份，revision 是新内容版本。
+ */
+export interface FileWriteResult {
+    file: FileReference;
+    revision: FileRevision;
+    bytesWritten: number;
+    mutationId: FileMutationId;
+}
+/**
+ * 任务观察的当前快照：taskId、status 与 updatedAt；progress、message 可选。
+ */
+export interface TaskObservationSnapshot {
+    taskId: string;
+    status: TaskStatus;
+    progress?: number;
+    message?: string;
+    updatedAt: string;
+}
+/**
+ * 任务观察流中的单条事件；payload 由服务端裁剪。
+ */
+export interface TaskObservationEvent {
+    id: string;
+    type: ("started" | "progress" | "succeeded" | "failed" | "cancelled" | "expired");
+    occurredAt: string;
+    payload: JsonValue;
+}
+/**
+ * 任务观察的一页结果：快照 + 有限事件页 + 游标。
+ */
+export interface TaskObservationBatch {
+    schemaVersion: 1;
+    taskId: string;
+    cursor: string;
+    reset: boolean;
+    hasMore: boolean;
+    snapshot: TaskObservationSnapshot;
+    /**
+     * @maxItems 100
+     */
+    events: TaskObservationEvent[];
+}
+/**
+ * 任务列表中的受限展示字段；key 是稳定机器键，value 是 Host 裁剪后的展示文本。
+ */
+export interface TaskListField {
+    /**
+     * 展示字段的稳定机器键，例如 machine 或 command。
+     */
+    key: string;
+    /**
+     * Host 完成授权与裁剪后的展示文本。
+     */
+    value: string;
+}
+/**
+ * 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[];
+}
+/**
+ * Host 已授权任务摘要的一页结果；nextCursor 缺失表示当前页已到末尾。
+ */
+export interface TaskListPage {
+    /**
+     * 任务列表页结构版本，当前固定为 1。
+     */
+    schemaVersion: 1;
+    /**
+     * 当前页中 Host 已授权的任务摘要。
+     *
+     * @maxItems 100
+     */
+    tasks: TaskListItem[];
+    /**
+     * 下一页的不透明游标；缺失表示当前列表已到末尾。
+     */
+    nextCursor?: string;
+}
+/**
+ * 受限 UI 状态读取结果。
+ */
+export interface UiStateResult {
+    found: boolean;
+    value?: JsonValue;
+}
+/**
+ * 受限 UI 状态写入结果。
+ */
+export interface UiStateWriteResult {
+    status: "saved";
+}
+/**
+ * 读取用户资料的结果；含稳定 userId 与展示名。
+ */
+export interface HostUserProfileReadOutput {
+    userId: string;
+    displayName: string;
+}
+/**
+ * 读取用户邮箱的结果；email 为地址或 null。
+ */
+export interface HostUserEmailReadOutput {
+    email: (string | null);
+}