@dp-bohrium/widget-sdk 0.5.0 → 0.7.0

package/schemas/host-runtime-config.schema.json

@@ -0,0 +1,305 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "host-runtime-config.schema.json",
+  "description": "Host 为一次 Widget 运行签发并下发给 agent-widget 的运行时配置，不直接发给 Widget。",
+  "title": "Widget Host Runtime Config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "hostApiVersion",
+    "configId",
+    "runId",
+    "mode",
+    "issuedAt",
+    "expiresAt",
+    "recheckAt",
+    "securityProfile",
+    "resourceBudget",
+    "runtime",
+    "network",
+    "bindings"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "hostApiVersion": { "const": 1 },
+    "configId": { "$ref": "#/$defs/Identifier" },
+    "hostId": { "$ref": "#/$defs/Identifier" },
+    "runId": { "$ref": "#/$defs/Identifier" },
+    "mode": { "$ref": "#/$defs/Mode" },
+    "issuedAt": { "$ref": "#/$defs/Timestamp" },
+    "expiresAt": { "$ref": "#/$defs/Timestamp" },
+    "recheckAt": { "$ref": "#/$defs/Timestamp" },
+    "securityProfile": { "const": "runtime-security-profile-v1" },
+    "resourceBudget": {
+      "$ref": "widget-runtime-contracts.schema.json#/$defs/ResourceBudget"
+    },
+    "runtime": { "$ref": "#/$defs/RuntimeAuthority" },
+    "network": { "$ref": "#/$defs/NetworkAuthority" },
+    "bindings": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "$ref": "#/$defs/LoadableBinding" },
+          { "$ref": "#/$defs/FallbackBinding" }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "LoadableBinding": {
+      "description": "可加载绑定：状态为 loadable，携带冻结版本、摘要、Manifest、启动地址与能力授权。",
+      "title": "LoadableBinding",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "bindingId",
+        "widgetId",
+        "widgetVersionId",
+        "digest",
+        "manifest",
+        "launch",
+        "grantedCapabilities"
+      ],
+      "properties": {
+        "status": { "const": "loadable" },
+        "bindingId": { "$ref": "#/$defs/Identifier" },
+        "widgetId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "digest": { "$ref": "#/$defs/Digest" },
+        "trustClass": {
+          "description": "控制面确认的信任等级；作者不能自行声明。",
+          "enum": ["external", "first-party"]
+        },
+        "runtimeProfile": {
+          "description": "控制面选择的部署配置；不授予 Cookie 或 Token 读取权限。",
+          "enum": ["public-isolated", "first-party-private"]
+        },
+        "manifest": {
+          "$ref": "widget-manifest.schema.json"
+        },
+        "launch": { "$ref": "#/$defs/Launch" },
+        "grantedCapabilities": { "$ref": "#/$defs/GrantedCapabilities" },
+        "serviceAccess": { "$ref": "#/$defs/WidgetServiceAccess" },
+        "serviceAuthorization": { "$ref": "#/$defs/HostServiceAuthorization" }
+      }
+    },
+    "HostServiceAuthorization": {
+      "title": "HostServiceAuthorization",
+      "description": "Host-only evidence bound to the exact reviewed Widget bundle and current user grant.",
+      "oneOf": [
+        { "$ref": "#/$defs/HostServiceAuthorizationRequired" },
+        { "$ref": "#/$defs/HostServiceAuthorizationGranted" }
+      ]
+    },
+    "HostServiceAuthorizationRequired": {
+      "description": "需用户授权的 Host 服务证据：状态为 authorization-required。",
+      "title": "HostServiceAuthorizationRequired",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "policy",
+        "status",
+        "hostId",
+        "widgetVersionId",
+        "bundleDigest",
+        "reviewRevision",
+        "reviewedPermissions",
+        "grantedPermissions",
+        "expiresAt"
+      ],
+      "properties": {
+        "kind": { "const": "host-service-authorization" },
+        "policy": { "const": "host-user-data-v1" },
+        "status": { "const": "authorization-required" },
+        "hostId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "bundleDigest": { "$ref": "#/$defs/Digest" },
+        "reviewRevision": { "$ref": "#/$defs/Identifier" },
+        "reviewedPermissions": {
+          "$ref": "widget-manifest.schema.json#/$defs/HostUserPermissions"
+        },
+        "grantedPermissions": {
+          "type": "array",
+          "maxItems": 0
+        },
+        "expiresAt": { "$ref": "#/$defs/Timestamp" }
+      }
+    },
+    "HostServiceAuthorizationGranted": {
+      "description": "已授予的 Host 服务证据：状态为 granted。",
+      "title": "HostServiceAuthorizationGranted",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "policy",
+        "status",
+        "hostId",
+        "widgetVersionId",
+        "bundleDigest",
+        "reviewRevision",
+        "grantRevision",
+        "reviewedPermissions",
+        "grantedPermissions",
+        "expiresAt"
+      ],
+      "properties": {
+        "kind": { "const": "host-service-authorization" },
+        "policy": { "const": "host-user-data-v1" },
+        "status": { "const": "granted" },
+        "hostId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "bundleDigest": { "$ref": "#/$defs/Digest" },
+        "reviewRevision": { "$ref": "#/$defs/Identifier" },
+        "grantRevision": { "$ref": "#/$defs/Identifier" },
+        "reviewedPermissions": {
+          "$ref": "widget-manifest.schema.json#/$defs/HostUserPermissions"
+        },
+        "grantedPermissions": {
+          "$ref": "widget-manifest.schema.json#/$defs/HostUserPermissions"
+        },
+        "expiresAt": { "$ref": "#/$defs/Timestamp" }
+      }
+    },
+    "FallbackBinding": {
+      "description": "降级绑定：状态为 fallback，不含 Bundle 地址、摘要、Manifest 或能力授权。",
+      "title": "FallbackBinding",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "bindingId",
+        "widgetId",
+        "widgetVersionId",
+        "contribution",
+        "reason"
+      ],
+      "properties": {
+        "status": { "const": "fallback" },
+        "bindingId": { "$ref": "#/$defs/Identifier" },
+        "widgetId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "contribution": {
+          "$ref": "widget-manifest.schema.json#/$defs/WidgetContributionConfig"
+        },
+        "reason": { "$ref": "#/$defs/FallbackReason" }
+      }
+    },
+    "RuntimeAuthority": {
+      "description": "运行域授权：origin 与 catalogRevision。",
+      "title": "RuntimeAuthority",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["origin", "catalogRevision"],
+      "properties": {
+        "origin": { "$ref": "#/$defs/RuntimeOrigin" },
+        "catalogRevision": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "profile": {
+          "enum": ["public-isolated", "first-party-private"]
+        }
+      }
+    },
+    "NetworkAuthority": {
+      "description": "网络授权：mode、policyVersion 与限制。",
+      "title": "NetworkAuthority",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "policyVersion", "limits"],
+      "properties": {
+        "mode": { "enum": ["runtime-consent", "unavailable"] },
+        "policyVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "limits": {
+          "$ref": "widget-runtime-contracts.schema.json#/$defs/WidgetNetworkLimits"
+        }
+      }
+    },
+    "GrantedCapabilities": {
+      "description": "已授予能力列表。",
+      "title": "GrantedCapabilities",
+      "type": "array",
+      "items": {
+        "$ref": "widget-runtime-contracts.schema.json#/$defs/GrantedCapability"
+      }
+    },
+    "Launch": {
+      "description": "一次性启动地址与有效期。",
+      "title": "Launch",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "expiresAt"],
+      "properties": {
+        "url": { "type": "string", "pattern": "^https?://" },
+        "expiresAt": { "$ref": "#/$defs/Timestamp" }
+      }
+    },
+    "RuntimeOrigin": {
+      "description": "隔离域运行源地址。",
+      "title": "RuntimeOrigin",
+      "type": "string",
+      "maxLength": 253,
+      "pattern": "^(?:https://[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]{1,5})?|http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\])(?::[0-9]{1,5})?)$"
+    },
+    "FallbackReason": {
+      "description": "降级原因枚举。",
+      "title": "FallbackReason",
+      "enum": [
+        "not-authorized",
+        "not-approved",
+        "delisted-for-new-use",
+        "revoked",
+        "host-api-unsupported",
+        "preview-not-allowed"
+      ]
+    },
+    "Digest": {
+      "description": "内容摘要；形如 sha256:<hex>。",
+      "title": "Digest",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "Identifier": {
+      "description": "不透明标识符。",
+      "title": "Identifier",
+      "type": "string",
+      "minLength": 1
+    },
+    "Mode": {
+      "description": "运行模式：preview 或 published。",
+      "title": "Mode",
+      "enum": ["preview", "published"]
+    },
+    "Timestamp": {
+      "description": "UTC 时间戳：YYYY-MM-DD + T + 非空格字符，以 Z 结尾。",
+      "title": "Timestamp",
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T[^ ]+Z$"
+    },
+    "WidgetServiceAccess": {
+      "title": "WidgetServiceAccess",
+      "description": "绑定当前不可变版本与摘要的审核投影；服务端每次调用仍须复核撤销和用户权限。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approvalId", "revision", "appId", "policyVersion", "expiresAt"],
+      "properties": {
+        "approvalId": { "$ref": "#/$defs/Identifier" },
+        "revision": { "$ref": "#/$defs/Identifier" },
+        "appId": { "$ref": "#/$defs/Identifier" },
+        "policyVersion": { "$ref": "#/$defs/Identifier" },
+        "expiresAt": { "$ref": "#/$defs/Timestamp" }
+      }
+    }
+  }
+}

package/schemas/widget-manifest.schema.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "widget-manifest.schema.json",
+  "description": "打包阶段生成的宿主 Widget 清单；name / description 仅用于首次展示默认值，widgetConfig 为冻结运行配置。",
+  "title": "Widget Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "widgetConfig"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "description": { "type": "string", "maxLength": 2000 },
+    "widgetConfig": { "$ref": "#/$defs/WidgetConfig" }
+  },
+  "$defs": {
+    "WidgetConfig": {
+      "description": "打包阶段生成的冻结 Widget 运行配置；字段由 CLI 从作者清单写入，作者不得再直接覆盖。",
+      "title": "WidgetConfig",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "hostApiVersion",
+        "widgetSdkVersion",
+        "entry",
+        "contribution",
+        "samples"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "hostApiVersion": { "const": 1 },
+        "widgetSdkVersion": { "$ref": "#/$defs/WidgetSdkVersion" },
+        "entry": { "$ref": "#/$defs/EntryPath" },
+        "contribution": { "$ref": "#/$defs/WidgetContributionConfig" },
+        "activationEvents": {
+          "description": "声明 Host 何时允许激活该 Widget；激活条件不授予事件读取能力。",
+          "$ref": "#/$defs/ActivationEvents"
+        },
+        "requestedCapabilities": {
+          "$ref": "#/$defs/RequestedCapabilities"
+        },
+        "requestedPermissions": { "$ref": "#/$defs/HostUserPermissions" },
+        "runtime": { "$ref": "#/$defs/RuntimeOptions" },
+        "samples": { "$ref": "#/$defs/Samples" }
+      }
+    },
+    "HostUserPermission": {
+      "description": "Widget 可申请读取的 Host 用户数据权限名：个人资料或邮箱。",
+      "title": "HostUserPermission",
+      "enum": ["host.user.profile.read", "host.user.email.read"]
+    },
+    "HostUserPermissions": {
+      "description": "Widget 申请的 Host 用户数据权限列表。",
+      "title": "HostUserPermissions",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/HostUserPermission" }
+    },
+    "RequestedCapabilities": {
+      "description": "Widget 申请的能力集合；声明仅表示申请，最终由 Host 按次授权。",
+      "title": "RequestedCapabilities",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "files": { "$ref": "#/$defs/FilesCapabilityRequest" },
+        "events": { "$ref": "#/$defs/EventsCapabilityRequest" },
+        "tasks": { "$ref": "#/$defs/TasksCapabilityRequest" },
+        "state": { "$ref": "#/$defs/StateCapabilityRequest" },
+        "actions": { "$ref": "#/$defs/ActionsCapabilityRequest" },
+        "network": { "$ref": "#/$defs/NetworkCapabilityRequest" },
+        "presentation": {
+          "$ref": "#/$defs/RequestedPresentationCapability"
+        },
+        "region": {
+          "$ref": "#/$defs/RequestedRegionCapability"
+        }
+      }
+    },
+    "FilesCapabilityRequest": {
+      "description": "文件能力的独立申请开关；保存已有文件必须单独申请 files.write 并获得 Host 授权，可写范围由 Host grant 决定。",
+      "title": "FilesCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "list": { "type": "boolean" },
+        "metadata": { "type": "boolean" },
+        "read": { "type": "boolean" },
+        "download": { "type": "boolean" },
+        "write": { "type": "boolean" }
+      }
+    },
+    "EventsCapabilityRequest": {
+      "description": "事件读取能力的申请；topics 声明要读取的事件主题。",
+      "title": "EventsCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["topics"],
+      "properties": {
+        "topics": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
+          }
+        }
+      }
+    },
+    "TasksCapabilityRequest": {
+      "description": "任务发现与观察能力的申请；list / watch 至少显式申请一项，已申请项固定为 true。",
+      "title": "TasksCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "list": { "const": true },
+        "watch": { "const": true }
+      }
+    },
+    "StateCapabilityRequest": {
+      "description": "受限 UI 状态读写能力的申请；read / write 分别声明。",
+      "title": "StateCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["read", "write"],
+      "properties": {
+        "read": { "type": "boolean" },
+        "write": { "type": "boolean" }
+      }
+    },
+    "ActionsCapabilityRequest": {
+      "description": "Host 自定义动作调用能力的申请；names 声明可调用的动作名。",
+      "title": "ActionsCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["names"],
+      "properties": {
+        "names": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
+          }
+        }
+      }
+    },
+    "NetworkCapabilityRequest": {
+      "description": "Host 托管网络能力的申请；fetch 固定为 true，目标域名由 Host 运行时按请求授权。",
+      "title": "NetworkCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fetch"],
+      "properties": {
+        "fetch": { "const": true }
+      }
+    },
+    "RequestedPresentationCapability": {
+      "description": "呈现能力的申请；surfaces 声明期望的呈现表面。",
+      "title": "RequestedPresentationCapability",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surfaces"],
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "uniqueItems": true,
+          "items": { "enum": ["floating", "overlay"] }
+        }
+      }
+    },
+    "RequestedRegionCapability": {
+      "description": "会话右侧区域替换能力的申请；当前仅支持 session.rightRail + replace。",
+      "title": "RequestedRegionCapability",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regions", "mode"],
+      "properties": {
+        "regions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true,
+          "items": { "const": "session.rightRail" }
+        },
+        "mode": { "const": "replace" }
+      }
+    },
+    "WidgetSdkVersion": {
+      "description": "构建该 Widget 时使用的 SDK 精确 SemVer 版本，不接受范围。",
+      "title": "WidgetSdkVersion",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+    },
+    "EntryPath": {
+      "description": "包内 ESM 入口路径；仅允许包内相对 POSIX 路径。",
+      "title": "EntryPath",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*://).+\\.m?js$"
+    },
+    "RuntimeOptions": {
+      "description": "运行时申请；worker 与 webAssembly 均为可选布尔开关。",
+      "title": "RuntimeOptions",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "boolean" },
+        "webAssembly": { "type": "boolean" }
+      }
+    },
+    "ActivationEvents": {
+      "title": "ActivationEvents",
+      "description": "Host 可用于启动 Widget 的公开激活信号。多个值表示任一信号命中即可激活；它们不授予 events.read 权限。工具名形式为 tool-call-<阶段>:<工具名>。",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/ActivationEvent" }
+    },
+    "ActivationEvent": {
+      "description": "公开 Widget 激活信号。高层 WidgetContext.events 使用事件 type；低层 events.read 的 topic 不填写在这里。",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "session.start",
+            "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"
+          ]
+        },
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^tool-call-(?:generating|waiting|running|result|error):[A-Za-z0-9_.:-]+$"
+        }
+      ]
+    },
+    "Samples": {
+      "description": "同版本 RenderRequest 测试样例；至少一个，request 为相对 .json 路径。",
+      "title": "Samples",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "request"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "title": { "type": "string", "minLength": 1, "maxLength": 128 },
+          "request": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*://).+\\.json$"
+          }
+        }
+      }
+    },
+    "WidgetContributionConfig": {
+      "description": "作者声明的扩展点配置：file-preview 声明扩展名集合，panel 绑定既有 Panel。",
+      "title": "WidgetContributionConfig",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "extensions"],
+          "properties": {
+            "type": { "const": "file-preview" },
+            "extensions": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 32,
+                "pattern": "^[a-z0-9][a-z0-9.-]*$"
+              }
+            }
+          }
+        },
+        { "$ref": "#/$defs/PanelContributionConfig" }
+      ]
+    },
+    "PanelContributionConfig": {
+      "title": "PanelContributionConfig",
+      "description": "绑定 Agent Widget 既有 Panel 的配置。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": {
+          "description": "Panel 贡献类型。",
+          "const": "panel"
+        },
+        "id": {
+          "description": "Host 注册和查找 Panel 时使用的稳定类型标识。",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_.:-]+$"
+        },
+        "placement": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind"],
+              "properties": {
+                "kind": { "const": "panel" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "region", "mode"],
+              "properties": {
+                "kind": { "const": "region" },
+                "region": { "const": "session.rightRail" },
+                "mode": { "const": "replace" }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}