@world-engines/agent-kit 0.1.0-alpha.0

package/assets/docs/development/generated/chatplay-sdk/chatplay-sdk.d.ts

@@ -0,0 +1,309 @@
+// AUTO-GENERATED by tools/gen-chatplay-sdk-descriptor.mjs
+// Runtime 3.1; 请勿手改 使用 --release 3.1 生成
+// 关联 ADR docs/adr/0105-editor-sdk-awareness.md
+// 真源 src/player-client/ui-shell/src/chat-play-sdk/runtime.ts 注入对象图
+// 消费侧 WebContainer 子工程 tsconfig.json include + IDE TypeScript LSP
+
+export interface SdkCapabilities {
+  readonly schemaVersion: number;
+  readonly capabilitiesShapeVersion: number;
+  readonly runtimeMajor: number;
+  readonly runtimePatch: number;
+  readonly protocolVersion: number;
+  readonly customStateMaxBytes: number;
+  readonly assetMaxBytes: number;
+  readonly supportsAssets: boolean;
+  readonly supportsEdit: boolean;
+  readonly supportsDelete: boolean;
+  readonly supportsWorldlines?: boolean;
+}
+
+export interface ChatPlayContext {
+  readonly scriptId: string;
+  readonly saveId: string;
+  readonly locale: string;
+  readonly theme: ThemeSnapshot;
+  readonly capabilities: SdkCapabilities;
+}
+
+export type CustomStateScope = 'public' | 'protected';
+export interface CustomStateEntry<T = unknown> {
+  readonly key: string;
+  readonly value: T;
+  readonly scope: CustomStateScope;
+  readonly authorizedUserIds: ReadonlyArray<string>;
+  readonly revision: number;
+}
+export interface CustomStateCommitResult {
+  readonly generation: number;
+  readonly changedKeys: ReadonlyArray<string>;
+  readonly entries: ReadonlyArray<CustomStateEntry>;
+  readonly replayed: boolean;
+}
+export interface CustomStateApi {
+  get<T = unknown>(key: string): Promise<CustomStateEntry<T> | undefined>;
+  set(key: string, value: unknown, options?: { readonly scope?: CustomStateScope; readonly authorizedUserIds?: ReadonlyArray<string> }): Promise<{ readonly ok: true; readonly generation: number }>;
+  delete(key: string): Promise<{ readonly ok: true; readonly generation: number }>;
+  keys(): Promise<string[]>;
+  commitBatch(batch: { readonly idempotencyKey: string; readonly expectedGeneration?: number; readonly mutations: ReadonlyArray<unknown> }): Promise<CustomStateCommitResult>;
+}
+
+export interface ReadonlyCustomStateApi {
+  get<T = unknown>(key: string): Promise<CustomStateEntry<T> | undefined>;
+  keys(): Promise<string[]>;
+}
+
+export interface CustomStateChangedEvent {
+  readonly generation: number;
+  readonly changedKeys: ReadonlyArray<string>;
+}
+
+export type TmwViewJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly TmwViewJsonValue[]
+  | { readonly [key: string]: TmwViewJsonValue };
+
+export interface TmwViewEventEmitReceipt {
+  readonly interactionId: string;
+  readonly nonce: string;
+}
+
+export interface TmwInteractionResult {
+  readonly interactionId: string;
+  readonly nonce: string;
+  readonly status: 'committed' | 'failed' | 'uncertain';
+  readonly code?: 'activation_failed' | 'activation_unconfirmed' | 'commit_sink_unavailable';
+}
+
+export interface TmwViewEventsApi {
+  emit(eventType: string, payload: Readonly<Record<string, TmwViewJsonValue>>, interactionId: string): TmwViewEventEmitReceipt;
+}
+
+/** manifest 声明的 committed-event 下行投影；opaqueId 仅可用于去重。 */
+export interface TmwDelivery {
+  readonly deliveryId: string;
+  readonly eventType: string;
+  readonly payload: Readonly<Record<string, null | boolean | number | string>>;
+  readonly opaqueId: string;
+}
+export type ThemeChoice = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+export interface ThemeSnapshot {
+  readonly choice: ThemeChoice;
+  readonly resolved: ResolvedTheme;
+}
+
+export interface PersistedListItem {
+  readonly id: string;
+  readonly saveId: string;
+  readonly role: 'user' | 'assistant' | 'system' | 'tool';
+  readonly text: string;
+  readonly ts: number;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+export interface SendHandle {
+  readonly messageId: Promise<string>;
+  readonly stream: ReadableStream<{ delta: string }>;
+  readonly done: Promise<{ fullContent: string }>;
+  abort(reason?: string): void;
+}
+
+export interface RegenerateHandle extends SendHandle {
+  readonly rollback: Promise<{
+    readonly removedMessageIds: ReadonlyArray<string>;
+    readonly deletedEntities: number;
+    readonly deletedRelations: number;
+  }>;
+}
+
+export interface EditAssistantMessageResult {
+  readonly kind: "assistant";
+  readonly removedMessageIds: ReadonlyArray<string>;
+  readonly deletedEntities: number;
+  readonly deletedRelations: number;
+}
+
+export interface EditUserMessageResult {
+  readonly kind: "user";
+  readonly id: string;
+  readonly content: string;
+}
+
+export interface AssetRecord {
+  readonly id: string;
+  readonly url: string;
+  readonly size: number;
+  readonly mime: string;
+  readonly filename: string;
+  readonly scriptId: string;
+  readonly createdTs: number;
+}
+
+export interface RewindResult {
+  readonly removedMessageIds: ReadonlyArray<string>;
+  readonly deletedEntities: number;
+  readonly deletedRelations: number;
+}
+
+export interface OwnedResource {
+  readonly type: string;
+  readonly uri: string;
+}
+
+export interface OwnedResourceGroup {
+  readonly node_id: string;
+  readonly attr_key: string;
+  readonly resources: ReadonlyArray<OwnedResource>;
+}
+
+export type ViewExposureTarget = 'llm' | 'trigger' | 'both';
+export type ViewToolBindingStatus = 'declared' | 'bound';
+
+export interface ViewToolBinding {
+  readonly exposureId: string;
+  readonly name: string;
+  readonly signatureHash: string;
+  readonly handlerEndpoint: string;
+}
+
+export interface ViewToolBindResult {
+  readonly exposureId: string;
+  readonly name: string;
+  readonly status: 'bound';
+  readonly boundAt: number;
+}
+
+export interface ViewExposureInfo {
+  readonly exposureId: string;
+  readonly name: string;
+  readonly description: string;
+  readonly target: ViewExposureTarget;
+  readonly signatureHash: string;
+  readonly status: ViewToolBindingStatus;
+  readonly handlerEndpoint?: string;
+  readonly boundAt?: number;
+}
+
+export interface ViewExposureListResult {
+  readonly manifestHash: string;
+  readonly revision: number;
+  readonly exposures: ReadonlyArray<ViewExposureInfo>;
+}
+
+export interface DirectorViewToolDescriptor {
+  readonly exposureId: string;
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly returns: unknown;
+  readonly manifestHash: string;
+  readonly manifestRevision: number;
+}
+
+
+export interface WorldlineMutationEffects {
+  readonly removedMessageIds: ReadonlyArray<string>;
+  readonly deletedEntities: number;
+  readonly deletedRelations: number;
+}
+export interface WorldlineSummary {
+  readonly worldlineId: string;
+  readonly title: string;
+  readonly parentWorldlineId: string | null;
+  readonly createdAtMs: number;
+  readonly updatedAtMs: number;
+  readonly revision: number;
+}
+export interface WorldlineListResult {
+  readonly activeWorldlineId: string;
+  readonly worldlineCount: number;
+  readonly worldlines: ReadonlyArray<WorldlineSummary>;
+}
+export interface ForkWorldlineResult extends WorldlineMutationEffects {
+  readonly worldlineId: string;
+  readonly activeWorldlineId: string;
+  readonly anchorMessageId: string;
+  readonly worldlineCount: number;
+}
+export interface ActivateWorldlineResult {
+  readonly worldlineId: string;
+  readonly activeWorldlineId: string;
+  readonly worldlineCount: number;
+  readonly messageCount: number;
+}
+export interface TrimWorldlineResult {
+  readonly worldlineId: string;
+  readonly activeWorldlineId: string;
+  readonly worldlineCount: number;
+  readonly removedOpCount: number;
+  readonly removedBlobCount: number;
+}
+export interface ReadonlyPlayerWorldlines {
+  list(): Promise<WorldlineListResult>;
+  fork(messageId: string, title?: string): Promise<ForkWorldlineResult>;
+  activate(worldlineId: string): Promise<ActivateWorldlineResult>;
+}
+
+export type ChatPlayEvent = 'messageAdded' | 'messageUpdated' | 'messageDeleted' | 'stateChanged' | 'streamStart' | 'streamDelta' | 'streamDone' | 'streamError' | 'localeChanged' | 'themeChanged' | 'saveForked' | 'resourceUnlocked' | 'saveCloned' | 'worldlineForked' | 'worldlineActivated' | 'worldlineTrimmed' | 'subagentStatus' | 'tmwDelivery' | 'interactionResult';
+
+export interface ChatPlayApi {
+  /** 同步握手 Promise 入口必先 await window.ChatPlay.ready 完成后才能调任何 wrapper */
+  readonly ready: Promise<ChatPlayContext>;
+  /** 同步取当前握手 context ready 之前返回 null */
+  context(): ChatPlayContext | null;
+  /** 拉当前 save 持久化消息列表 支持 after/before 切片与 limit 截断 */
+  listMessages(opts?: { readonly after?: string; readonly before?: string; readonly limit?: number }): Promise<PersistedListItem[]>;
+  /** 通过宿主受控 chat.sendUserMessage 发送非空 user 消息；不暴露底层 RPC */
+  sendUserMessage(text: string): Promise<{ readonly messageId: string; readonly turnId: string }>;
+  /** 列出当前 script 名下所有资产 */
+  listAssets(): Promise<AssetRecord[]>;
+  /** 把 asset id 解析成运行时可访问 URL (blob:) */
+  getAssetUrl(id: string): Promise<string>;
+  /** 读 view 端自定义状态 缺省 key 返回 undefined */
+  loadCustomState(key: string): Promise<unknown>;
+  /** 列出当前 save 下所有 custom state key */
+  listCustomStateKeys(): Promise<string[]>;
+  /** 按当前 view 作用域只读查询自定义状态；写入、删除和批量提交不暴露给 TMW3 view */
+  readonly customState: ReadonlyCustomStateApi;
+  /** TMW3 view interaction capability；仅可提交 manifest 预声明 eventType，返回 interactionId 与 nonce 回执；最终激活结果通过 interactionResult 事件异步回传，不生成或扩大宿主权限 */
+  readonly events: TmwViewEventsApi;
+  /** TMW3 same-Save worldline API. Scope is host-derived; no Save identifier is accepted or returned. */
+  readonly worldline: ReadonlyPlayerWorldlines;
+  /** 取当前剧本元信息 */
+  getScenarioMeta(): Promise<{ scriptId: string; title: string; schemaVersion: number }>;
+  /** 取进度比 0..1 */
+  getProgress(): Promise<number>;
+  /** 读取当前 save 的触发器变量；scope 由宿主固定为 save，View 不可改写 */
+  getVariable(name: string): Promise<unknown>;
+  /** 读取当前 save 中指定节点或边的触发器解锁状态 */
+  getUnlock(target: "node" | "edge", id: string): Promise<{ readonly unlocked: boolean }>;
+  /** 返回当前已解锁资源 按节点和属性锚点分组 */
+  getOwnedResources(): Promise<OwnedResourceGroup[]>;
+  /** 请求宿主打开模型设置面板；只返回是否接受意图，不读取或返回任何配置 */
+  openModelSettings(): Promise<{ ok: true }>;
+  /** 取当前 UI locale (zh / en / ja) */
+  getLocale(): Promise<string>;
+  /** 只读获取宿主主题选择和当前解析后的明暗配色 */
+  getTheme(): Promise<ThemeSnapshot>;
+  /** 同步返回 SDK runtime 版本号 */
+  runtimeVersion(): { readonly major: number; readonly patch: number };
+  /** 订阅 SDK 事件 返回取消订阅函数；interactionResult 只关联本 iframe 的 interactionId/nonce，不暴露 committed event envelope、capability 或原始错误；tmwDelivery 不参与互动结果关联 */
+  on(event: "tmwDelivery", listener: (delivery: TmwDelivery) => void): () => void;
+  on(event: "interactionResult", listener: (result: TmwInteractionResult) => void): () => void;
+  on(event: "stateChanged", listener: (event: CustomStateChangedEvent) => void): () => void;
+  on(event: "worldlineForked", listener: (result: ForkWorldlineResult) => void): () => void;
+  on(event: "worldlineActivated", listener: (result: ActivateWorldlineResult) => void): () => void;
+  on(event: ChatPlayEvent, listener: (payload: unknown) => void): () => void;
+}
+
+declare global {
+  interface Window {
+    ChatPlay: ChatPlayApi;
+  }
+}
+
+export {};