@webskill/sdk 0.2.6 → 0.2.8

package/dist/rolldown-runtime-BOF7iYI8.js

@@ -0,0 +1,55 @@
+import { createRequire } from "node:module";
+
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
+
+//#endregion
+export { __require as a, __reExport as i, __esmMin as n, __toCommonJS as o, __exportAll as r, __toESM as s, __commonJSMin as t };

package/dist/sandboxWorkerEntry.js

@@ -151,6 +151,7 @@ function setupNetworkGuards(task) {
 */
 const internalExit = process.reallyExit.bind(process);
 function stripProcessEscapeHatches() {
+	const remaining = [];
 	for (const key of [
 		"binding",
 		"_linkedBinding",
@@ -158,9 +159,17 @@ function stripProcessEscapeHatches() {
 		"openStdin",
 		"reallyExit",
 		"abort"
-	]) try {
-		Reflect.deleteProperty(process, key);
-	} catch {}
+	]) {
+		try {
+			Reflect.deleteProperty(process, key);
+		} catch {}
+		if (key in process) remaining.push(key);
+	}
+	if (remaining.length > 0) {
+		const err = /* @__PURE__ */ new Error(`Sandbox hardening failed: cannot remove process escape hatches (${remaining.join(", ")})`);
+		err.code = "TOOL_EXECUTION_FAILED";
+		throw err;
+	}
 }
 async function main() {
 	const task = workerData;

package/dist/{index-DRlYzdr2.d.ts → skillVersionStore-B7rGjtMi-BgnQho9v.d.ts}

@@ -1,5 +1,5 @@
-import { B as SkillManifest, C as FileStat, G as SkillsLockfile, L as SkillInstallSource, T as JsonSchema, _ as RenderResultRequest, o as InteractionRequest, q as VerifyResult, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits } from "./types-CKm5G_eQ-krKWW8WV.js";
-import { N as NetworkPolicy, Q as ScriptExecutor, X as SchemaInferer, Z as ScriptExecutionContext, b as FsArtifactStore, d as BridgeCapabilities, it as ToolResult, nt as ToolDefinition, u as ApprovalScope, x as FsMemoryStore } from "./index-DJOha4b6.js";
+import { K as SkillInstallSource, M as FileStat, N as FileSystemProvider, O as ArchiveLimits, P as JsonSchema, U as SkillCatalogEntry, Y as SkillManifest, _ as RenderResultRequest, et as SkillsLockfile, nt as VerifyResult, o as InteractionRequest, s as InteractionResponse, v as UiBridge } from "./types-AmKCKJn_-BogJPQHU.js";
+import { N as NetworkPolicy, Q as ScriptExecutor, X as SchemaInferer, Z as ScriptExecutionContext, b as FsArtifactStore, d as BridgeCapabilities, it as ToolResult, nt as ToolDefinition, u as ApprovalScope, x as FsMemoryStore } from "./index-QrHtAudz.js";
 import { Readable, Writable } from "node:stream";
 //#region ../node/dist/index.d.ts
 //#region src/fs/nodeFs.d.ts
@@ -237,4 +237,129 @@ declare function exportArchive(fs: FileSystemProvider, skillRoot: string, option
 /** 只解出归档中的 webskill.skill-manifest.json 条目（安装前预览） */
 declare function readArchiveManifest(fs: FileSystemProvider, archivePath: string): Promise<SkillManifest>;
 //#endregion
-export { NodeScriptExecutor as a, ProcessSandboxOptions as c, SkillManager as d, exportArchive as f, NodeFS as i, SandboxOptions as l, FileArtifactStore as n, OxcSchemaInferer as o, readArchiveManifest as p, FileMemoryStore as r, ProcessSandboxExecutor as s, CliUiBridge as t, SandboxedScriptExecutor as u };
+//#region ../governance/dist/skillVersionStore-B7rGjtMi.d.ts
+//#region src/types.d.ts
+type CandidateStatus = 'draft' | 'pending-review' | 'approved' | 'published' | 'rejected';
+type CandidateSource = 'runtime-miss' | 'document' | 'manual';
+type CandidateRisk = 'low' | 'medium' | 'high';
+interface CandidateFile {
+  path: string;
+  kind: 'skill-md' | 'script' | 'reference' | 'asset';
+  content: string;
+}
+interface CandidateSkill {
+  id: string;
+  name: string;
+  description: string;
+  status: CandidateStatus;
+  source: CandidateSource;
+  risk: CandidateRisk;
+  riskReasons: string[];
+  files: CandidateFile[];
+  suggestedTests?: string[];
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+interface AuditEvent {
+  id: string;
+  type: string;
+  target: string;
+  actor?: string;
+  ts: string;
+  data?: Record<string, unknown>;
+  /** hash 链：上一条事件的 hash（首条为 GENESIS） */
+  prevHash?: string;
+  /** 本事件规范化载荷 + prevHash 的 sha256 */
+  hash?: string;
+}
+interface AuditLog {
+  append(event: Omit<AuditEvent, 'id' | 'ts'> & {
+    id?: string;
+    ts?: string;
+  }): Promise<AuditEvent>;
+  query(filter: {
+    target?: string;
+    type?: string;
+    since?: string;
+  }): Promise<AuditEvent[]>;
+}
+interface SkillVersion {
+  versionId: string;
+  parentVersionId?: string;
+  createdAt: string;
+  reason: string;
+  manifest: SkillManifest;
+  auditEventId?: string;
+  /** 发布时捕获的技能归档（zip 相对路径，applyRollback 恢复用；0.2.0 起记录） */
+  archivePath?: string;
+}
+type SkillState = 'active' | 'quarantined' | 'deprecated' | 'disabled';
+//#endregion
+//#region src/candidate/candidateStore.d.ts
+/** 逐文件持久化的候选存储：<managedRoot>/.webskill/candidates/<id>.json */
+declare class CandidateStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+  });
+  save(candidate: CandidateSkill): Promise<void>;
+  get(id: string): Promise<CandidateSkill>;
+  list(): Promise<CandidateSkill[]>;
+  updateStatus(id: string, status: CandidateStatus, now?: string): Promise<CandidateSkill>;
+}
+/** 硬门禁：仅 published 可转换为 Catalog 条目，否则 APPROVAL_REQUIRED */
+declare function candidateToCatalogEntry(candidate: CandidateSkill): SkillCatalogEntry;
+//#endregion
+//#region src/approval/policies.d.ts
+interface ApprovalDecision {
+  needsHuman: boolean;
+  reason: string;
+}
+interface ApprovalPolicy {
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+/** 默认策略：任何候选都必须人工审批 */
+declare class AlwaysHumanApprovalPolicy implements ApprovalPolicy {
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+/** 规则组合策略：首个命中的规则胜出，全部未命中走 fallback（默认 AlwaysHuman） */
+declare class CompositeApprovalPolicy implements ApprovalPolicy {
+  #private;
+  constructor(rules: Array<(candidate: CandidateSkill) => ApprovalDecision | undefined>, fallback?: ApprovalPolicy);
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+//#endregion
+//#region src/versioning/skillVersionStore.d.ts
+/** 版本存储：manifest 快照 + parentVersionId 链；回滚 = 追加新版本（谱系不断）。
+ *  保留策略：maxArchivesPerSkill（默认 5）超出时清理最旧版本（json + zip 归档一并删除）。 */
+declare class SkillVersionStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+    now?: () => string;
+    createId?: () => string;
+    audit?: AuditLog;
+    /** 每技能保留的版本/归档上限（默认 5，超出清理最旧） */
+    maxArchivesPerSkill?: number;
+  });
+  add(skillName: string, input: {
+    reason: string;
+    manifest: SkillManifest;
+    parentVersionId?: string;
+    archive?: Uint8Array;
+  }): Promise<SkillVersion>;
+  /** 读取版本归档字节（applyRollback 用；未捕获归档的旧版本 → GOVERNANCE_FAILED） */
+  readArchive(skillName: string, versionId: string): Promise<Uint8Array>;
+  list(skillName: string): Promise<SkillVersion[]>;
+  get(skillName: string, versionId: string): Promise<SkillVersion>;
+  /** 回滚：基于旧 manifest 追加新版本 + skill.rolled_back 审计 */
+  rollback(skillName: string, targetVersionId: string, input: {
+    actor?: string;
+    reason?: string;
+  }): Promise<SkillVersion>;
+}
+//#endregion
+export { ProcessSandboxExecutor as C, SkillManager as D, SandboxedScriptExecutor as E, exportArchive as O, OxcSchemaInferer as S, SandboxOptions as T, CliUiBridge as _, AuditLog as a, NodeFS as b, CandidateSkill as c, CandidateStore as d, CompositeApprovalPolicy as f, candidateToCatalogEntry as g, SkillVersionStore as h, AuditEvent as i, readArchiveManifest as k, CandidateSource as l, SkillVersion as m, ApprovalDecision as n, CandidateFile as o, SkillState as p, ApprovalPolicy as r, CandidateRisk as s, AlwaysHumanApprovalPolicy as t, CandidateStatus as u, FileArtifactStore as v, ProcessSandboxOptions as w, NodeScriptExecutor as x, FileMemoryStore as y };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { c as LlmClient, d as LlmResponse, f as LlmStreamEvent, h as MemoryStore, l as LlmCompleteInput, n as ArtifactStore, o as InteractionRequest, s as InteractionResponse, t as Artifact, v as UiBridge } from "./types-CKm5G_eQ-krKWW8WV.js";
+import { c as LlmClient, d as LlmResponse, f as LlmStreamEvent, h as MemoryStore, l as LlmCompleteInput, n as ArtifactStore, o as InteractionRequest, s as InteractionResponse, t as Artifact, v as UiBridge } from "./types-AmKCKJn_-BogJPQHU.js";
 import { a as loadGoogleConfigFromEnv, i as loadAnthropicConfigFromEnv, n as LlmEnvConfig, o as loadLlmConfigFromEnv, r as ProviderEnvConfig } from "./env-BPUBZCwJ-4jat_SVG.js";
 //#region ../runtime/dist/testing.d.ts
 //#region src/llm/mockLlmClient.d.ts

package/dist/{types-CKm5G_eQ-krKWW8WV.d.ts → types-AmKCKJn_-BogJPQHU.d.ts}

@@ -405,7 +405,7 @@ declare function escapeXml(text: string): string;
 declare function renderAvailableSkillsXml(catalog: SkillCatalog): string;
 declare const xmlRenderer: CatalogRenderer;
 //#endregion
-//#region ../runtime/dist/types-CKm5G_eQ.d.ts
+//#region ../runtime/dist/types-AmKCKJn_.d.ts
 //#region src/llm/streamTypes.d.ts
 /** 流式 LLM 事件（OpenAI SSE / Vercel fullStream 统一映射） */
 type LlmStreamEvent = {
@@ -437,6 +437,8 @@ interface LlmToolCall {
   id: string;
   name: string;
   arguments: Record<string, unknown>;
+  /** 流式拼接后的 arguments 不是合法 JSON 时的错误描述；设置时 arguments 不可信 */
+  argumentsParseError?: string;
 }
 interface LlmResponse {
   content?: string;
@@ -565,6 +567,125 @@ interface RenderResultRequest {
   blocks: RenderBlock[];
   artifacts?: Artifact[];
 }
+/** A user action exposed by a generative UI surface. @experimental */
+interface UiSurfaceAction {
+  id: string;
+  label: string;
+  intent: 'submit' | 'cancel' | 'select' | 'download' | 'refresh';
+  disabled?: boolean;
+  /** Requests that the producing run waits for this action before continuing. @experimental */
+  awaitResponse?: boolean;
+  /** Runtime-generated action capability; model-provided values are never trusted. @experimental */
+  nonce?: string;
+}
+/** A runtime-owned request for a user action on a rendered UI surface. @experimental */
+interface UiSurfaceActionRequest {
+  runId: string;
+  surfaceId: string;
+  actionId: string;
+  intent: UiSurfaceAction['intent'];
+  nonce: string;
+}
+/** A structured action returned by a renderer to the waiting run. @experimental */
+interface UiSurfaceActionResponse extends UiSurfaceActionRequest {
+  value?: Record<string, unknown>;
+  cancelled?: boolean;
+}
+/** Serializable draft values for forms that belong to one interrupted run. @experimental */
+type UiSurfaceDrafts = Record<string, Record<string, unknown>>;
+/** A structured form field rendered inside a generative UI surface. @experimental */
+interface UiSurfaceFormField {
+  name: string;
+  label: string;
+  type: 'text' | 'number' | 'date' | 'textarea' | 'select' | 'multi-select' | 'toggle' | 'file';
+  required?: boolean;
+  description?: string;
+  defaultValue?: unknown;
+  options?: Array<{
+    label: string;
+    value: unknown;
+  }>;
+}
+/** Framework-neutral generative UI surface. @experimental */
+type UiSurface = {
+  kind: 'form';
+  id: string;
+  title?: string;
+  fields: UiSurfaceFormField[];
+  actions: UiSurfaceAction[];
+} | {
+  kind: 'chart';
+  id: string;
+  chart: ChartSpec;
+  actions?: UiSurfaceAction[];
+} | {
+  kind: 'table';
+  id: string;
+  columns: string[];
+  rows: unknown[][];
+  actions?: UiSurfaceAction[];
+} | {
+  kind: 'metric';
+  id: string;
+  label: string;
+  value: string | number;
+  trend?: 'up' | 'down' | 'neutral';
+} | {
+  kind: 'file';
+  id: string;
+  path: string;
+  mimeType?: string;
+  size?: number;
+  actions?: UiSurfaceAction[];
+} | {
+  kind: 'custom';
+  id: string;
+  component: string;
+  props: unknown;
+  actions?: UiSurfaceAction[];
+};
+/** A bounded mutation applied to an existing UI surface. @experimental */
+interface UiSurfacePatch {
+  op: 'replace' | 'merge' | 'append';
+  path: string;
+  value: unknown;
+}
+/** Incremental lifecycle event for a framework-neutral generative UI surface. @experimental */
+type UiSurfaceEvent = {
+  runId?: string;
+} & ({
+  type: 'open';
+  surface: UiSurface;
+} | {
+  type: 'patch';
+  id: string;
+  revision: number;
+  operations: UiSurfacePatch[];
+} | {
+  type: 'complete';
+  id: string;
+  revision: number;
+} | {
+  type: 'error';
+  id: string;
+  code: string;
+  message: string;
+} | {
+  type: 'cancel';
+  id: string;
+});
+/** Persisted state of a generative UI surface. @experimental */
+interface UiSurfaceSnapshot {
+  surface: UiSurface;
+  revision: number;
+  status: 'active' | 'complete' | 'error' | 'cancelled';
+  /** Immutable producing run; supplied on open to support session persistence and replay. */
+  runId?: string;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
 /** @stable */
 interface UiBridge {
   request(input: InteractionRequest): Promise<InteractionResponse>;
@@ -577,6 +698,12 @@ interface UiBridge {
   }): Promise<void>;
   /** 定义即可，阶段 7 消费 */
   renderResult?(input: RenderResultRequest): Promise<void>;
+  /** Framework-neutral generative UI surface stream. @experimental */
+  renderSurface?(event: UiSurfaceEvent): Promise<void>;
+  /** Waits for an action declared with awaitResponse; optional for compatibility with legacy bridges. @experimental */
+  requestSurfaceAction?(input: UiSurfaceActionRequest): Promise<UiSurfaceActionResponse>;
+  /** Best-effort cleanup when a surface action wait times out or is cancelled. @experimental */
+  cancelSurfaceAction?(nonce: string): void | Promise<void>;
   /** 流式文本增量（流式 LLM 路径下由 AgentLoop 转发） */
   onTextDelta?(runId: string, delta: string): Promise<void> | void;
 }
@@ -616,4 +743,4 @@ interface MemoryStore {
   transaction?<T>(scope: string, fn: (inner: MemoryStore) => Promise<T>): Promise<T>;
 }
 //#endregion
-export { buildCatalog as $, SKILL_NAME_MAX_LENGTH as A, SkillManifest as B, FileStat as C, RemoteUrlPolicy as D, MemoryFS as E, SkillDiscovery as F, SkillsLockfile as G, SkillPackManifest as H, SkillDocument as I, WebSkillError as J, ValidationReport as K, SkillInstallSource as L, SKILL_PACK_FILE as M, SkillCatalog as N, SKILLS_LOCKFILE as O, SkillCatalogEntry as P, atomicWriteText as Q, SkillIssue as R, DiscoveryResult as S, JsonSchema as T, SkillReader as U, SkillMetadata as V, SkillSource as W, assertRemoteUrlAllowed as X, WebSkillErrorCode as Y, assertSafePathSegment as Z, RenderResultRequest as _, unzipWithLimits as _t, InteractionPolicy as a, exportSkills as at, CatalogRenderer as b, xmlRenderer as bt, LlmClient as c, messageOf as ct, LlmResponse as d, parseSkillPackManifest as dt, buildManifest as et, LlmStreamEvent as f, readResponseWithLimit as ft, RenderBlock as g, resolveInsideRoot as gt, MemoryStore as h, resolveArchiveLimits as ht, FormField as i, escapeXml as it, SKILL_NAME_PATTERN as j, SKILL_MANIFEST_FILE as k, LlmCompleteInput as l, normalizePath as lt, LlmToolSpec as m, renderCatalogJson as mt, ArtifactStore as n, checkSkillRules as nt, InteractionRequest as o, isValidSkillName as ot, LlmToolCall as p, renderAvailableSkillsXml as pt, VerifyResult as q, ChartSpec as r, computeDigest as rt, InteractionResponse as s, jsonRenderer as st, Artifact as t, checkDependencyCycles as tt, LlmMessage as u, parseSkillMarkdown as ut, UiBridge as v, validateSkills as vt, FileSystemProvider as w, DEFAULT_ARCHIVE_LIMITS as x, ArchiveLimits as y, verifyManifest as yt, SkillLocation as z };
+export { SkillSource as $, DEFAULT_ARCHIVE_LIMITS as A, SKILL_NAME_PATTERN as B, UiSurfaceDrafts as C, renderCatalogJson as Ct, UiSurfaceSnapshot as D, validateSkills as Dt, UiSurfacePatch as E, unzipWithLimits as Et, MemoryFS as F, SkillDocument as G, SkillCatalog as H, RemoteUrlPolicy as I, SkillLocation as J, SkillInstallSource as K, SKILLS_LOCKFILE as L, FileStat as M, FileSystemProvider as N, ArchiveLimits as O, verifyManifest as Ot, JsonSchema as P, SkillReader as Q, SKILL_MANIFEST_FILE as R, UiSurfaceActionResponse as S, renderAvailableSkillsXml as St, UiSurfaceFormField as T, resolveInsideRoot as Tt, SkillCatalogEntry as U, SKILL_PACK_FILE as V, SkillDiscovery as W, SkillMetadata as X, SkillManifest as Y, SkillPackManifest as Z, RenderResultRequest as _, messageOf as _t, InteractionPolicy as a, assertRemoteUrlAllowed as at, UiSurfaceAction as b, parseSkillPackManifest as bt, LlmClient as c, buildCatalog as ct, LlmResponse as d, checkSkillRules as dt, SkillsLockfile as et, LlmStreamEvent as f, computeDigest as ft, RenderBlock as g, jsonRenderer as gt, MemoryStore as h, isValidSkillName as ht, FormField as i, WebSkillErrorCode as it, DiscoveryResult as j, CatalogRenderer as k, xmlRenderer as kt, LlmCompleteInput as l, buildManifest as lt, LlmToolSpec as m, exportSkills as mt, ArtifactStore as n, VerifyResult as nt, InteractionRequest as o, assertSafePathSegment as ot, LlmToolCall as p, escapeXml as pt, SkillIssue as q, ChartSpec as r, WebSkillError as rt, InteractionResponse as s, atomicWriteText as st, Artifact as t, ValidationReport as tt, LlmMessage as u, checkDependencyCycles as ut, UiBridge as v, normalizePath as vt, UiSurfaceEvent as w, resolveArchiveLimits as wt, UiSurfaceActionRequest as x, readResponseWithLimit as xt, UiSurface as y, parseSkillMarkdown as yt, SKILL_NAME_MAX_LENGTH as z };

package/dist/ui-react.d.ts

@@ -1,6 +1,21 @@
-import { _ as RenderResultRequest, o as InteractionRequest, s as InteractionResponse, v as UiBridge } from "./types-CKm5G_eQ-krKWW8WV.js";
+import { C as UiSurfaceDrafts, D as UiSurfaceSnapshot, S as UiSurfaceActionResponse, _ as RenderResultRequest, b as UiSurfaceAction, o as InteractionRequest, s as InteractionResponse, v as UiBridge, w as UiSurfaceEvent, x as UiSurfaceActionRequest } from "./types-AmKCKJn_-BogJPQHU.js";
+import { B as UiSpecNode } from "./index-7DVaZJU7.js";
+import { z } from "zod";
+import { ComponentType, ReactNode } from "react";
 //#region ../ui-react/dist/index.d.ts
+//#region src/surfaceStore.d.ts
+/** Observable, revision-checked snapshot store for framework-neutral UI surfaces. @experimental */
+declare class UiSurfaceStore {
+  #private;
+  subscribe: (listener: () => void) => (() => void);
+  get snapshots(): readonly UiSurfaceSnapshot[];
+  apply(event: UiSurfaceEvent): void;
+}
+//#endregion
 //#region src/bridgeState.d.ts
+interface ReactBridgeStateOptions {
+  onSurfaceDraftChange?(runId: string, surfaceId: string, value: Record<string, unknown>): Promise<void> | void;
+}
 /**
  * React 桥接状态：UiBridge 实现 + useSyncExternalStore 兼容订阅。
  * 应用创建实例传给 Runtime 与组件：<InteractionForm bridge={bridge} />。
@@ -8,10 +23,17 @@ import { _ as RenderResultRequest, o as InteractionRequest, s as InteractionResp
 declare class ReactBridgeState implements UiBridge {
   #private;
   pending: InteractionRequest | null;
+  pendingSurfaceAction: UiSurfaceActionRequest | null;
   latestResult: RenderResultRequest | null;
+  readonly surfaceStore: UiSurfaceStore;
   /** 当前流式 runId（并发 run 隔离：新 runId 重置文本） */
   streamingRunId: string | null;
   streamingText: string;
+  constructor(options?: ReactBridgeStateOptions);
+  get surfaceSnapshots(): readonly UiSurfaceSnapshot[];
+  surfaceDrafts(runId: string): UiSurfaceDrafts;
+  restoreSurfaceDrafts(runId: string, drafts: UiSurfaceDrafts | undefined): void;
+  setSurfaceDraft(runId: string, surfaceId: string, value: Record<string, unknown>): void;
   /** React useSyncExternalStore 兼容订阅 */
   subscribe: (listener: () => void) => (() => void);
   request(input: InteractionRequest): Promise<InteractionResponse>;
@@ -20,6 +42,11 @@ declare class ReactBridgeState implements UiBridge {
   /** runtime 交互超时/取消：卸载表单并以 cancelled resolve pending Promise（防悬挂 + 残留） */
   cancel(id: string): void;
   renderResult(input: RenderResultRequest): Promise<void>;
+  renderSurface(event: UiSurfaceEvent): Promise<void>;
+  requestSurfaceAction(input: UiSurfaceActionRequest): Promise<UiSurfaceActionResponse>;
+  /** Resolves exactly one pending action capability; stale or duplicate nonces are ignored. */
+  resolveSurfaceAction(response: UiSurfaceActionResponse): boolean;
+  cancelSurfaceAction(nonce: string): void;
   onTextDelta(runId: string, delta: string): Promise<void>;
 }
 //#endregion
@@ -41,4 +68,113 @@ declare function StreamingText({ bridge }: {
   bridge: ReactBridgeState;
 }): import("react").JSX.Element | null;
 //#endregion
-export { InteractionForm, ReactBridgeState, ResultBlocks, StreamingText };
+//#region src/surfaceRegistry.d.ts
+interface CustomSurfaceActionEvent {
+  surfaceId: string;
+  actionId: string;
+  intent: UiSurfaceAction['intent'];
+  nonce?: string;
+  value?: Record<string, unknown>;
+}
+interface RegisteredSurfaceProps<Props> {
+  surfaceId: string;
+  props: Props;
+  actions: readonly UiSurfaceAction[];
+  onAction?(event: CustomSurfaceActionEvent): void;
+}
+interface SurfaceRegistration<Props> {
+  schema: z.ZodType<Props>;
+  component: ComponentType<RegisteredSurfaceProps<Props>>;
+}
+interface RegisteredSurface<Props> {
+  schema: z.ZodType<Props>;
+  component: ComponentType<RegisteredSurfaceProps<Props>>;
+}
+/** Explicit allowlist for Native custom surfaces. @experimental */
+declare class SurfaceRegistry {
+  #private;
+  register<Props>(name: string, registration: SurfaceRegistration<Props>): this;
+  get(name: string): RegisteredSurface<unknown> | undefined;
+}
+//#endregion
+//#region src/components/UiSurfaceList.d.ts
+interface UiSurfaceActionEvent {
+  runId?: string;
+  surfaceId: string;
+  actionId: string;
+  intent: UiSurfaceAction['intent'];
+  nonce?: string;
+  value?: Record<string, unknown>;
+}
+interface UiSurfaceListProps {
+  bridge: ReactBridgeState;
+  /** Limits the live renderer to a producing run; omit to render the full store. */
+  runId?: string;
+  registry?: SurfaceRegistry;
+  onAction?(event: UiSurfaceActionEvent): void;
+}
+interface UiSurfaceSnapshotListProps {
+  snapshots: readonly UiSurfaceSnapshot[];
+  registry?: SurfaceRegistry;
+  onAction?(event: UiSurfaceActionEvent): void;
+  drafts?: UiSurfaceDrafts;
+  onDraftChange?(event: {
+    runId: string;
+    surfaceId: string;
+    value: Record<string, unknown>;
+  }): void;
+}
+/** Renders Native surface snapshots, including persisted assistant-message history. @experimental */
+declare function UiSurfaceSnapshotList({ snapshots, registry, onAction, drafts, onDraftChange }: UiSurfaceSnapshotListProps): import("react").JSX.Element | null;
+/** Renders the current Native surface snapshots exposed by a React bridge. @experimental */
+declare function UiSurfaceList({ bridge, runId, registry, onAction }: UiSurfaceListProps): import("react").JSX.Element;
+//#endregion
+//#region src/catalog/NativeSpecSurface.d.ts
+/** native registry 覆盖的组件名；与 catalog 的一致性由测试强制（21 号文档 §5.2） */
+declare const NATIVE_SPEC_COMPONENTS: readonly string[];
+interface NativeSpecSurfaceProps {
+  surfaceId: string;
+  spec: UiSpecNode;
+  actions: readonly UiSurfaceAction[];
+  registry?: SurfaceRegistry;
+  onAction?(event: CustomSurfaceActionEvent): void;
+}
+/**
+ * Native 档的 catalog registry：把声明树渲染成 ui-kit 组件。
+ * 越界组件名不静默降级，渲染成英文错误行（21 号文档 §8 第 5 条）。
+ */
+declare function NativeSpecSurface({ surfaceId, spec, actions, registry, onAction }: NativeSpecSurfaceProps): import("react").JSX.Element;
+//#endregion
+//#region src/catalog/JsonRenderSpecSurface.d.ts
+interface JsonRenderSpecSurfaceProps {
+  spec: UiSpecNode;
+}
+/**
+ * `vercel` 档：同一份 catalog 声明树交给 json-render 的 Registry 渲染。
+ * `@json-render/*` 是 optional peer，未安装时给出英文说明而不是空白。
+ */
+declare function JsonRenderSpecSurface({ spec }: JsonRenderSpecSurfaceProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/catalog/OpenUiSpecSurface.d.ts
+interface OpenUiSpecSurfaceProps {
+  spec: UiSpecNode;
+}
+/**
+ * `openui` 档：同一份 catalog 声明树经 openui-lang 交给 OpenUI 的 Renderer。
+ * `@openuidev/react-lang` 是 optional peer，未安装时给出英文说明而不是空白。
+ */
+declare function OpenUiSpecSurface({ spec }: OpenUiSpecSurfaceProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/catalog/catalogComponents.d.ts
+type CatalogNodeProps = {
+  props: Record<string, unknown>;
+  children?: ReactNode;
+};
+/**
+ * catalog 16 个组件的展示实现：json-render 与 OpenUI 两档共用同一份，
+ * 避免"一个 catalog、多套 registry"退化成多套各自演进的视觉。
+ * 交互（表单值收集 / action 回传）由各档的宿主组件负责。
+ */
+declare const catalogComponentImpls: Record<string, (input: CatalogNodeProps) => ReactNode>;
+//#endregion
+export { type CatalogNodeProps, type CustomSurfaceActionEvent, InteractionForm, JsonRenderSpecSurface, type JsonRenderSpecSurfaceProps, NATIVE_SPEC_COMPONENTS, NativeSpecSurface, type NativeSpecSurfaceProps, OpenUiSpecSurface, type OpenUiSpecSurfaceProps, ReactBridgeState, type RegisteredSurfaceProps, ResultBlocks, StreamingText, type SurfaceRegistration, SurfaceRegistry, type UiSurfaceActionEvent, UiSurfaceList, type UiSurfaceListProps, UiSurfaceSnapshotList, type UiSurfaceSnapshotListProps, UiSurfaceStore, catalogComponentImpls };