@qfei-design/make-ai-assistant 0.2.12 → 0.2.14

package/PUBLIC_API.md

@@ -5,7 +5,7 @@
 - `@qfei-design/make-ai-assistant`：headless Artifact、会话、模板注册和 transport 合同。
 - `@qfei-design/make-ai-assistant/react`：React 助手壳、ArtifactRenderer 和平台模板。
 - `@qfei-design/make-ai-assistant/sse`：基于 Fetch、ReadableStream 的浏览器/现代 Node SSE transport；公开声明不要求 TypeScript `DOM` lib。
-- `@qfei-design/make-ai-assistant/make-app`：Make App AI 语义协议 adapter；网络请求、认证和 EventSource 创建均由宿主注入。
+- `@qfei-design/make-ai-assistant/make-app`：Make App v1 UI adapter；使用标准 Client，异步读取能力后返回 AssistantTransport。
 - `@qfei-design/make-ai-assistant/make-console`：Make Console Agent/Session/Run 语义协议 adapter；认证请求和 EventSource 创建由 Console 宿主注入。
 - `@qfei-design/make-ai-assistant/testing`：Mock transport 和通用 fixtures，仅用于开发、测试与 Gallery。
 - `@qfei-design/make-ai-assistant/styles.css`：助手壳与默认模板样式。
@@ -13,6 +13,8 @@
 
 禁止宿主从 `src`、`dist` 或包内部路径导入。
 
+- `@qfei-design/make-ai-assistant/client`：无 React/DOM 类型依赖的 v1 HTTP/字节流客户端与 ApiError。
+
 ## Headless exports
 
 - `validateArtifact` / `parseArtifact`
@@ -40,18 +42,17 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
 - `MakeAiAssistant`：默认右下角浮动入口与右侧抽屉；支持受控开关、自定义 launcher，以及
   `brandName` 对默认“{品牌名} AI 助手”标题的覆盖。`title` 可覆盖完整标题；`assistantName` /
   `userName` / `userAvatarUrl` 可显示当前登录人的名称和头像；未传入时用户侧不显示身份信息。
-  `subtitle` 用于显示宿主传入的当前对象（兼容移除旧接入中的“只读分析 ·”前缀）；`privacyNotice`
-  会在对象右侧的问号 Tooltip 中展示，并根据图标与可用视口选择相邻方向，而非单独的广播行。头栏默认高度为 50px，可通过 `headerHeight` 或
+  `subtitle` 与 `privacyNotice` 仅继续接受旧调用传入的值以保持类型兼容，不会参与渲染或发送到
+  transport；新宿主不应传入。头栏默认高度为 50px，可通过 `headerHeight` 或
   `--make-ai-header-height` 覆盖。内置浮动入口可通过 `launcherPosition` 设置为 `bottom-left`、
   `bottom-right`、`top-left`、`top-right`、`left-center` 或 `right-center`；默认值为 `bottom-right`。
   自定义 `launcher` 自行负责位置。标准位置只读取对应锚点的
   `--make-ai-launcher-left`、`--make-ai-launcher-right`、`--make-ai-launcher-top` 或
   `--make-ai-launcher-bottom` 变量；窄屏使用对应的 `--make-ai-launcher-mobile-*` 变量，另一侧始终为
   `auto`。
-  桌面端抽屉可从左边缘 12px 热区向左拖宽，初始计算宽度（默认 480px，或宿主的
-  `--make-ai-drawer-width`）同时作为拖拽下限；热区激活时展示 2px 主题色提示线，宿主可通过
-  `--make-ai-drawer-resize-line` 覆盖其颜色；手柄支持左右方向键微调。不大于 560px 的视口保持全宽，
-  不提供宽度调整。
+  桌面端抽屉默认 560px，宿主可通过 `--make-ai-drawer-width` 覆盖固定宽度；包内最大宽度规则为
+  `min(1024px, 72vw)`，但不会压缩固定宽度，可通过 `maxDrawerWidth` 传入像素值设置明确上限。抽屉不提供左侧拖拽或键盘宽度调整；
+  标题栏右侧“新建对话”左侧提供全屏/退出全屏按钮，全屏只作用于组件抽屉布局。不大于 560px 的视口保持全宽。
   面板按自身容器宽度适配：达到 560px 时扩展内容区间距和阅读宽度，达到 760px 时 Markdown 表格
   优先按可用宽度分列并换行；宿主可使用 `--make-ai-panel-gutter-wide` 覆盖扩展状态内边距。
   首次打开后关闭抽屉只隐藏 Drawer，不卸载 `AssistantPanel`，不会中断正在进行的生成。
@@ -59,8 +60,8 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
   省略 `suggestions` 时显示包内默认推荐问题，传入 `[]` 时隐藏推荐问题。
 - `AssistantPanel`：不带 Drawer 的嵌入式会话面板；支持 `brandName`、`title`、`assistantName` /
   `subtitle` / `userName` / `userAvatarUrl` / `privacyNotice` / `headerHeight`。默认品牌为“Make”，
-  默认显示“AI 助手”；用户侧默认不展示名称或头像，宿主提示默认不展示。这些字段只参与本地 React
-  渲染，不会进入 transport 请求。嵌入式面板包含图标化复制回答、可选安全重新生成、图标化回到最新消息、
+  默认显示“AI 助手”；用户侧默认不展示名称或头像。`subtitle` 与 `privacyNotice` 不参与渲染；
+  其余展示字段只参与本地 React 渲染，不会进入 transport 请求。嵌入式面板包含图标化复制、喜欢/不喜欢、可选安全重新生成、图标化回到最新消息、
   仅在生成中显示的处理步骤、错误重试、键盘提交与 reduced-motion 处理。
 - `ArtifactRenderer`：注册表驱动的单 Artifact 渲染器。
 - `createPlatformArtifactRegistry`
@@ -84,7 +85,8 @@ Promise rejection。`onActionError` 自身同步抛错或返回 rejected Promise
 不会污染宿主的全局未处理异常。
 
 成功回答的复制操作以图标按钮展示，悬浮或聚焦时显示“复制”提示，保留“复制回答”的无障碍名称，
-只复制该 assistant message 的文本内容；复制失败只在本地 UI 反馈并记录不含回答正文的错误类型。AI 回答正文会按标题、
+只复制该 assistant message 的文本内容；持久 assistant message 的反馈操作同样使用图标按钮，悬浮或聚焦时显示
+“喜欢”或“不喜欢”提示，并保留可读的无障碍名称。复制失败只在本地 UI 反馈并记录不含回答正文的错误类型。AI 回答正文会按标题、
 段落、列表、强调、反引号代码片段和 Markdown 表格行做轻量结构化展示；该渲染不执行 HTML、JSX、
 CSS 或 JavaScript。对话排版默认分为四级：标题和用户问题为 14px、AI 正文与结构化结果数据为
 13px、身份/状态/操作等辅助信息为 12px、来源/时间/复制反馈等非关键注释为 11px。宿主可通过
@@ -173,19 +175,13 @@ UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢
 
 ## Make App transport
 
-`/make-app` 导出 `createMakeAppAssistantTransport`、`MakeAppAssistantTransportOptions`、`MakeAppAssistantScope`、`MakeAppAssistantEventSourceFactory` 及相关结构类型。完整回调与接线示例见 [当前 Make App 合同](docs/make-app-integration.md)。
-
-宿主注入 resolveScope、会话/SSE/上传语义回调及可选的 readContent：listAgents、createChat、listChats、getChat、updateChat、deleteChat、loadHistory、sendMessage、getResponse、cancelResponse、setFeedback、startUpload、getUpload、uploadPart、completeUpload、eventSourceFactory。JSON 回调返回裸对象，204 返回 void；宿主能够无损读取二进制时再提供 readContent，并返回 Uint8Array。
-
-`resolveScope(context)` 返回 appKey、agentId 和随登录身份变化的 identityKey。包只用于作用域绑定与缓存失效，服务器仍独立鉴权。每个异步回调接受 AbortSignal；包不提供部署 URL、不读 Cookie、不导入认证 SDK。
+`/client` 导出 createMakeAgentClient、ApiError、Client 与 AuthenticatedTransport 等平台中立类型。固定 apiVersion=v1，basePath 默认 /api/make/app/ai。详细方法、错误、预算和幂等责任见 [稳定客户端合同](docs/make-app-integration.md)。
 
-`AssistantTransport` 原地增加 listAgents、listConversations、create/get/update/deleteConversation、get/cancelResponse、setFeedback、上传/内容方法与 watchResponse。方法在通用 interface 上可选，Make App adapter 实现全部。loadConversation options 可传 threadId/cursor，返回 nextCursor/hasMore；分页读取不会隐式创建 Chat。
+`/make-app` 导出异步 createMakeAppAssistantTransport({ client, agentId, historyLimit?, signal? })，通过能力发现后返回 AssistantTransport。宿主只注入一个正式认证 HTTP 传输、App/身份和 Agent；身份变化时调用 client.dispose() 并重建实例。
 
-输入 message 可携带 parts；响应事件增加 response.accepted/state/output_item.added/output_text.delta/output_item.done/snapshot/reconciled/terminal。每个 Run、item 和 part 的身份独立，持久助手 messageId 用于反馈。`AssistantConversationState.responses` 保存响应集合；输入可以合并到同一 Run，不按调用次数伪造 Turn。
+标准 SDK 将新增响应元数据安全投影；未知事件保留名称/游标，未知内容块保留 originalKind/textFallback，不执行未知动作。输入仍严格验证。v1 的 cursor 为不透明字符串，ResponseSnapshot 必含 terminal 和 snapshotRevision。框架中立的 AssistantTransport 仍允许 Console/测试适配器的本地序号，但 Make App v1 不接受数字 cursor。
 
-features 增加 conversationManagement、feedback、attachments、modelInputKinds。Make App 的 newConversation/remoteCancellation 和 attachments 为 true，regeneration 为 false；modelInputKinds 是宿主对模型输入的声明，附件的实际接受与拒绝由服务端处理。未注入 readContent 时 transport 不暴露该方法，React UI 也不展示无效的下载/预览按钮。historyLimit 范围 1—200；maxEventCharacters 默认 1,000,000；重连由 adapter 单独负责。完整快照属于覆盖，不能当新 delta。
-
-根入口导出 AssistantContentPart、AssistantMedia、AssistantChat、AssistantChatPage、AssistantAgent、AssistantFeedback、AssistantUpload、AssistantResponseSnapshot、AssistantResponseEvent 等类型，仍无 React/DOM File 依赖。文件读取与 Object URL 留在 React/宿主边界。
+Chat.titlePending 缺失按 false；摘要完成通过同一 Client 的详情刷新立即反映到会话列表。SSE 只更新响应视图，反馈使用历史中真正的 messageId，关闭订阅不会远程取消运行。
 
 ## Make Console transport
 
@@ -233,3 +229,7 @@ Artifact 的 `action.target` 只是 JSON 意图。宿主必须根据当前权限
 - 未注册模板安全降级；
 - `presentation.template` 不会触发代码加载；
 - 新模板不得复用已有 id。
+
+## 自动标题更新
+
+AssistantChat 必须包含 titlePending: boolean。首条长消息摘要排队或生成时为 true，完成、失败或手工命名后为 false。消息受理后读取一次会话详情；列表或当前会话存在待摘要状态时，每秒通过已认证 getConversation 回调刷新对应详情，按 revision 合并。正文终态不停止标题检查；摘要完成即停止，作用域切换、删除或卸载会取消请求。迟到的较低 revision 详情或列表不会覆盖新标题。

package/README.md

@@ -5,9 +5,11 @@
 ## Install
 
 ```bash
-pnpm add @qfei-design/make-ai-assistant@^0.2.0
+pnpm add --save-exact @qfei-design/make-ai-assistant@VERSION
 ```
 
+VERSION 替换为完成本地验收的发布版本，提交 lockfile 固定制品。
+
 ## Quick start
 
 ```tsx
@@ -93,12 +95,12 @@ const hostTheme: MakeAiTheme = {
 宿主 `--make-color-primary` > 包内默认值。`background` 会控制内容区基础背景；`surface`、`text` 等其余中性色字段为兼容保留，
 不会改变内置默认样式；它们仍会写入 `renderContext.themeStyle`，供自定义 Artifact 模板自行使用。
 
-桌面端抽屉默认宽度为 480px，且该初始宽度是用户拖拽时的最小宽度。最大宽度默认是 `min(1024px, 72vw)`，宿主可通过 `maxDrawerWidth` 传入像素值覆盖；小于最小宽度的配置会回退至最小宽度。鼠标移至抽屉左边缘的 12px 热区时才会显示 2px 主题色拖拽提示线（可通过 `--make-ai-drawer-resize-line` 覆盖），可向左拖宽；获得焦点后也可用左、右方向键以 16px 调整宽度。不大于 560px 的视口保持全宽展示，不显示拖拽手柄。
+桌面端抽屉默认宽度为 560px，宿主仍可通过 `--make-ai-drawer-width` 覆盖固定宽度。包内最大宽度规则为 `min(1024px, 72vw)`，但不会压缩默认或宿主指定的固定宽度；宿主可通过 `maxDrawerWidth` 传入像素值设置明确上限。抽屉不再提供左侧拖拽或键盘调整宽度；标题栏右侧“新建对话”左侧提供全屏/退出全屏按钮，全屏只作用于本组件的抽屉布局，不调用浏览器原生全屏。不大于 560px 的视口保持全宽展示。
 
 面板使用容器查询而非页面视口响应宽度：回答区、结构化结果、代码块和 Markdown 表格会随抽屉可用宽度扩展；达到 760px 时，表格优先按可用宽度分列并换行，长段落和列表仍限制在 96ch 内以保障阅读性。窄容器中的 Markdown 表格保留横向滚动保护，并使用细窄的中性灰滚动条。宿主可通过 `--make-ai-panel-gutter-wide` 覆盖扩展抽屉的内边距。
 
 成功的 AI 回答会显示仅含图标的复制按钮，鼠标悬浮或键盘聚焦时显示“复制”提示，按钮保留
-“复制回答”的无障碍名称；复制只处理该回答的文本内容，失败时会在本地 UI 内提示，不会把回答正文写入日志。AI 回答正文会按标题、
+“复制回答”的无障碍名称；持久回答的喜欢/不喜欢也使用同样的图标交互，并分别显示“喜欢”与“不喜欢”提示。复制只处理该回答的文本内容，失败时会在本地 UI 内提示，不会把回答正文写入日志。AI 回答正文会按标题、
 段落、列表、强调、代码片段和 Markdown 表格行做轻量结构化展示，不执行 HTML，也不引入 Markdown
 运行时依赖。对话排版默认分为四级：标题和用户问题为 14px、AI 正文与结构化结果数据为 13px、身份/状态/操作等辅助信息为
 12px、来源/时间/复制反馈等非关键注释为 11px。宿主可通过
@@ -192,23 +194,23 @@ const assistantTransport = createSseAssistantTransport({
 });
 ```
 
-Make App 使用专用 adapter 与当前唯一公开契约：
+客户端入口为 `@qfei-design/make-ai-assistant/client`。App 宿主提供正式认证 HTTP 传输，标准客户端统一管理 18 项接口、固定 `/v1` 路径、响应解码、分页、重试、字节上传与 SSE。`/make-app` 把客户端结果映射到已有助手 UI 状态机。
 
 ```ts
+import { createMakeAgentClient } from "@qfei-design/make-ai-assistant/client";
 import { createMakeAppAssistantTransport } from "@qfei-design/make-ai-assistant/make-app";
 
-const assistantTransport = createMakeAppAssistantTransport({
-  ...makeAppAiClient,
-  resolveScope: () => ({ appKey, agentId, identityKey }),
-  modelInputKinds: ["text"],
+const client = createMakeAgentClient({
+  apiVersion: "v1",
+  scope: { appKey, identityKey },
+  transport: authenticatedTransport,
 });
+const assistantTransport = await createMakeAppAssistantTransport({ client, agentId });
+// 将 assistantTransport 传入 AssistantPanel / MakeAiAssistant。
+// App、用户或租户改变时，取消旧连接并 client.dispose()，重新创建实例。
 ```
 
-`makeAppAiClient` 实现 Agent/Chat 管理、分页历史、消息、响应快照、独立取消、反馈、上传和 EventSource，并可在宿主具备无损二进制认证读取能力时注入原件读取。完整类型与示例见 [Make App 接入说明](docs/make-app-integration.md) 和 [宿主示例](examples/make-app/main.tsx)。网络与认证由宿主注入，identityKey 随当前用户/租户变化。
-
-内置面板支持持久会话列表、新建、改名、置顶/删除、反馈与附件队列。历史 cursor=-1 从最早事件正向分页，空可见页仍可能存在后续事件。首次加载不隐式建会话，用户新建或主动发送才创建。item/part 增量、完整文本覆盖、快照恢复和持久 messageId 对账由包统一处理。
-
-停止显示“停止中”，直到服务端确认终态；中断订阅不取消后台 Run。当前 Make App 不提供重新生成语义，也不传 context/capabilities 或伪造 Artifact。附件入口固定为“上传文件或图片”；modelInputKinds 仅描述宿主模型能力，服务端根据消息 parts 决定是否接受媒体类型。单条消息文本最多 8 KiB UTF-8，最多 32 个 parts。
+`AuthenticatedTransport.request` 只执行一次已认证 I/O，返回 status、headers 和 AsyncIterable<Uint8Array>。`retryOwner: "sdk"` 由 SDK 按幂等语义做有限重试；`retryOwner: "transport"` 不叠加 SDK 重试。宿主沿正式 auth.api 处理登录、401/403 和 Cookie，SSE/二进制成功体不经过 JSON 或 text() 缓冲。SDK 不读取 Token、Cookie、LocalStorage 或 Provider key。
 
 Make Console 可以使用独立 adapter：
 
@@ -259,3 +261,7 @@ pnpm build
 ```
 
 发布统一走 GitLab CI；不要从功能分支本地执行 npm publish。
+
+### 会话自动标题
+
+Make App 的 Chat 包含 titlePending。首条长消息的摘要完成后，助手通过每秒一次的待摘要会话详情刷新自动更新列表，独立于正文流式完成时间；短标题和手工命名结束等待，旧 revision 不覆盖当前状态。详情刷新经过标准 client.chats.get 和正式认证传输，不增加登录或直连模型逻辑。

package/capabilities.json

@@ -70,9 +70,10 @@
       "name": "Make App AI transport",
       "category": "integration",
       "status": "experimental",
-      "summary": "宿主注入的多会话管理、反馈、附件与 item/part SSE、快照恢复和远程取消。",
+      "summary": "标准 v1 Client 支撑多会话、反馈、附件、SSE、单调快照与显式取消；宿主注入正式认证 HTTP 传输。",
       "docPath": "PUBLIC_API.md",
       "relatedExports": [
+        "@qfei-design/make-ai-assistant/client:createMakeAgentClient",
         "@qfei-design/make-ai-assistant/make-app:createMakeAppAssistantTransport",
         "AssistantTransport"
       ]

package/dist/client-protocol.d.ts

@@ -0,0 +1,24 @@
+import type { AgentPage, Capabilities, Chat, ChatPage, Feedback, HistoryPage, Media, OutputPart, ResponseSnapshot, Upload } from "./client-types.js";
+export declare const record: (value: unknown) => Record<string, unknown>;
+export declare const id: (value: unknown) => string;
+export declare const text: (value: unknown, maximum?: number, empty?: boolean) => string;
+export declare const number: (value: unknown, minimum?: number, maximum?: number) => number;
+export declare const boolean: (value: unknown) => boolean;
+export declare const array: (value: unknown, maximum: number) => unknown[];
+export declare function requestKeys(value: object, keys: readonly string[]): void;
+export declare function uuid(value: unknown): string;
+export declare function cursor(value: unknown, empty?: boolean): string;
+export declare function pageFields(value: Record<string, unknown>): {
+    nextCursor: string;
+    hasMore: boolean;
+};
+export declare function readChat(raw: unknown, appKey: string, agentId?: string, chatId?: string): Chat;
+export declare function readChatPage(raw: unknown, appKey: string, agentId: string): ChatPage;
+export declare function readAgents(raw: unknown, appKey: string): AgentPage;
+export declare function readMedia(raw: unknown): Media;
+export declare function readParts(raw: unknown): OutputPart[];
+export declare function readFeedback(raw: unknown): Feedback;
+export declare function readHistory(raw: unknown): HistoryPage;
+export declare function readSnapshot(raw: unknown, chatId: string, responseId: string): ResponseSnapshot;
+export declare function readUpload(raw: unknown, expectedId?: string): Upload;
+export declare function readCapabilities(raw: unknown, appKey: string, agentId: string): Capabilities;

package/dist/client-types.d.ts

@@ -0,0 +1,420 @@
+/** v1 公共客户端类型；网络通过宿主认证传输，React 与业务动作留在上层。 */
+export type ApiVersion = "v1";
+export type Id = string;
+export type Cursor = string;
+export type OpenString<Known extends string> = Known | (string & {});
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+export interface RetryOptions {
+    readonly maxAttempts?: number;
+    readonly maxDelayMs?: number;
+}
+export interface StreamOptions {
+    readonly connectTimeoutMs?: number;
+    readonly idleTimeoutMs?: number;
+    readonly maxDurationMs?: number;
+}
+export interface CallOptions {
+    readonly signal?: AbortSignalLike;
+    readonly timeoutMs?: number;
+}
+export interface Scope {
+    readonly appKey: Id;
+    readonly identityKey: string;
+}
+export interface HttpRequest {
+    readonly method: "GET" | "POST" | "PATCH" | "DELETE" | "PUT";
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: Uint8Array;
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: AsyncIterable<Uint8Array>;
+}
+/** 由宿主正式认证适配器实现；不允许在浏览器 SDK 内读取 Token/Cookie。 */
+export interface AuthenticatedTransport {
+    readonly retryOwner: "sdk" | "transport";
+    request(request: HttpRequest, options?: CallOptions): Promise<HttpResponse>;
+}
+export interface ClientOptions {
+    readonly apiVersion?: ApiVersion;
+    readonly basePath?: string;
+    readonly scope: Scope;
+    readonly transport: AuthenticatedTransport;
+    readonly retry?: RetryOptions;
+    readonly stream?: StreamOptions;
+    readonly timeoutMs?: number;
+    readonly maxJsonBytes?: number;
+    readonly maxEventBytes?: number;
+    readonly onDiagnostic?: (event: {
+        operation: string;
+        code?: string;
+        requestId?: string;
+        attempts?: number;
+    }) => void;
+}
+export interface PageOptions {
+    readonly cursor?: Cursor;
+    readonly limit?: number;
+}
+export interface IterateOptions extends CallOptions {
+    readonly maxPages: number;
+    readonly maxItems: number;
+}
+export interface Agent {
+    readonly agentId: Id;
+    readonly appKey: Id;
+    readonly name: string;
+}
+export interface AgentPage {
+    readonly agents: readonly Agent[];
+    readonly nextCursor: Cursor;
+    readonly hasMore: boolean;
+}
+export interface Chat {
+    readonly chatId: Id;
+    readonly appKey: Id;
+    readonly agentId: Id;
+    readonly title: string;
+    readonly status: "active" | "deleted";
+    readonly revision: number;
+    readonly pinned: boolean;
+    readonly pinnedAt?: string | null;
+    readonly createdAt: string;
+    readonly lastActivityAt: string;
+    readonly titlePending?: boolean;
+}
+export interface ChatPage {
+    readonly chats: readonly Chat[];
+    readonly nextCursor: Cursor;
+    readonly hasMore: boolean;
+}
+export interface CreateChatInput {
+    readonly agentId: Id;
+    readonly requestId: string;
+    readonly title?: string;
+}
+export type UpdateChatInput = {
+    readonly chatId: Id;
+    readonly expectedRevision: number;
+} & ({
+    readonly title: string;
+    readonly pinned?: boolean;
+} | {
+    readonly pinned: boolean;
+    readonly title?: string;
+});
+export interface Media {
+    readonly contentRef: Id;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly digestSha256: string;
+}
+export type KnownMediaKind = "image" | "file" | "audio" | "video";
+export type InputPart = {
+    readonly id: string;
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly id: string;
+    readonly kind: KnownMediaKind;
+    readonly name?: string;
+    readonly media: Media;
+};
+export type OutputPart = {
+    readonly id?: Id;
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly id?: Id;
+    readonly kind: KnownMediaKind;
+    readonly name?: string;
+    readonly media: Media;
+} | {
+    readonly id?: Id;
+    readonly kind: "unknown";
+    readonly originalKind: string;
+    readonly textFallback?: string;
+};
+export type SendMessageInput = {
+    readonly chatId: Id;
+    readonly messageId: string;
+} & ({
+    readonly text: string;
+    readonly parts?: never;
+} | {
+    readonly parts: readonly InputPart[];
+    readonly text?: never;
+});
+export interface Accepted {
+    readonly chatId: Id;
+    readonly messageId: Id;
+    readonly responseId: Id;
+    readonly acceptedCursor?: Cursor;
+}
+export interface Feedback {
+    readonly id: Id;
+    readonly rating: "like" | "dislike" | "none";
+    readonly revision: number;
+    readonly reason?: string;
+    readonly comment?: string;
+}
+export interface FeedbackInput {
+    readonly chatId: Id;
+    readonly messageId: Id;
+    readonly requestId: string;
+    readonly rating: "like" | "dislike" | "none";
+    readonly reason?: string;
+    readonly comment?: string;
+}
+export interface StoredMessage {
+    readonly messageId: Id;
+    readonly role: "user" | "assistant";
+    readonly cursor: Cursor;
+    readonly createdAt: string;
+    readonly text: string;
+    readonly parts?: readonly OutputPart[];
+    readonly responseId?: Id;
+    readonly feedback?: Feedback;
+}
+export interface HistoryPage {
+    readonly messages: readonly StoredMessage[];
+    readonly nextCursor: Cursor;
+    readonly hasMore: boolean;
+}
+export interface OutputItem {
+    readonly itemId: Id;
+    readonly partId: Id;
+    readonly text: string;
+    readonly final: boolean;
+    readonly revision: number;
+    readonly parts?: readonly OutputPart[];
+}
+export type ResponseStatus = OpenString<"queued" | "dispatched" | "running" | "completed" | "failed" | "cancelled">;
+export interface PublicError {
+    readonly code: string;
+    readonly message: string;
+    readonly requestId?: string;
+    readonly details?: readonly {
+        readonly code?: string;
+        readonly target?: string;
+        readonly message?: string;
+    }[];
+}
+export interface ResponseRef {
+    readonly chatId: Id;
+    readonly responseId: Id;
+}
+export interface ResponseSnapshot extends ResponseRef {
+    readonly status: ResponseStatus;
+    readonly terminal: boolean;
+    readonly snapshotRevision: number;
+    readonly items: readonly OutputItem[];
+    readonly cancelRequested?: boolean;
+    readonly error?: PublicError;
+}
+export type ResponseEvent = {
+    readonly kind: "subscribed";
+    readonly responseId: Id;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "state";
+    readonly responseId: Id;
+    readonly status: ResponseStatus;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "itemAdded";
+    readonly responseId: Id;
+    readonly itemId: Id;
+    readonly partId: Id;
+    readonly sequence: number;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "textDelta";
+    readonly responseId: Id;
+    readonly itemId: Id;
+    readonly partId: Id;
+    readonly sequence: number;
+    readonly delta: string;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "itemDone";
+    readonly responseId: Id;
+    readonly itemId: Id;
+    readonly partId: Id;
+    readonly sequence: number;
+    readonly text: string;
+    readonly final: boolean;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "reset";
+    readonly responseId: Id;
+    readonly reason: string;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "snapshot";
+    readonly snapshot: ResponseSnapshot;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "completed" | "failed" | "cancelled";
+    readonly responseId: Id;
+    readonly code?: string;
+    readonly cursor?: Cursor;
+} | {
+    readonly kind: "unknown";
+    readonly responseId: Id;
+    readonly name: string;
+    readonly cursor?: Cursor;
+};
+export interface StartUploadInput {
+    readonly chatId: Id;
+    readonly fileId: string;
+    readonly name: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly digestSha256?: string;
+}
+export interface ContentReference {
+    readonly kind: "reference";
+    readonly contentRef: Id;
+    readonly sizeBytes: number;
+    readonly digestSha256: string;
+}
+export interface Upload {
+    readonly id: Id;
+    readonly status: OpenString<"uploading" | "ready" | "expired" | "cancelled">;
+    readonly name: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly partSize: number;
+    readonly completedParts: readonly number[];
+    readonly expiresAt?: string;
+    readonly content?: ContentReference;
+}
+export interface ReplayableBytes {
+    readonly sizeBytes: number;
+    read(offset: number, length: number, options?: CallOptions): Promise<Uint8Array>;
+}
+export interface ContentDownload {
+    readonly contentType?: string;
+    readonly contentLength?: number;
+    readonly body: AsyncIterable<Uint8Array>;
+}
+export interface Limits {
+    readonly maxInputTextBytes: number;
+    readonly maxMessageBytes: number;
+    readonly maxInputParts: number;
+    readonly maxUploadBytes: number;
+    readonly uploadPartBytes: number;
+    readonly maxConcurrentUploads: number;
+    readonly maxSseEventBytes: number;
+}
+export interface Capabilities {
+    readonly apiVersion: ApiVersion;
+    readonly appKey: Id;
+    readonly agentId: Id;
+    readonly features: readonly string[];
+    readonly modelInputKinds: readonly string[];
+    readonly limits: Limits;
+    readonly revision?: string;
+}
+export interface Client {
+    readonly scope: Scope;
+    readonly apiVersion: ApiVersion;
+    readonly capabilities: {
+        get(input: {
+            agentId: Id;
+        }, options?: CallOptions): Promise<Capabilities>;
+    };
+    readonly agents: {
+        list(page?: PageOptions, options?: CallOptions): Promise<AgentPage>;
+    };
+    readonly chats: {
+        create(input: CreateChatInput, options?: CallOptions): Promise<Chat>;
+        list(input: {
+            agentId: Id;
+        } & PageOptions, options?: CallOptions): Promise<ChatPage>;
+        get(input: {
+            chatId: Id;
+        }, options?: CallOptions): Promise<Chat>;
+        update(input: UpdateChatInput, options?: CallOptions): Promise<Chat>;
+        delete(input: {
+            chatId: Id;
+            expectedRevision: number;
+        }, options?: CallOptions): Promise<void>;
+        iterate(input: {
+            agentId: Id;
+        } & PageOptions, options: IterateOptions): AsyncIterable<Chat>;
+    };
+    readonly messages: {
+        send(input: SendMessageInput, options?: CallOptions): Promise<Accepted>;
+        list(input: {
+            chatId: Id;
+        } & PageOptions, options?: CallOptions): Promise<HistoryPage>;
+        iterate(input: {
+            chatId: Id;
+        } & PageOptions, options: IterateOptions): AsyncIterable<StoredMessage>;
+        sendAndWatch(input: SendMessageInput, options?: CallOptions): Promise<{
+            readonly accepted: Accepted;
+            readonly events: AsyncIterable<ResponseEvent>;
+        }>;
+    };
+    readonly responses: {
+        get(input: ResponseRef, options?: CallOptions): Promise<ResponseSnapshot>;
+        subscribe(input: ResponseRef & {
+            cursor?: Cursor;
+        }, options?: CallOptions): AsyncIterable<ResponseEvent>;
+        cancel(input: ResponseRef, options?: CallOptions): Promise<ResponseSnapshot>;
+        waitForTerminal(input: ResponseRef, options: CallOptions & {
+            timeoutMs: number;
+            pollIntervalMs?: number;
+        }): Promise<ResponseSnapshot>;
+    };
+    readonly feedback: {
+        set(input: FeedbackInput, options?: CallOptions): Promise<Feedback>;
+    };
+    readonly uploads: {
+        start(input: StartUploadInput, options?: CallOptions): Promise<Upload>;
+        get(input: {
+            chatId: Id;
+            uploadId: Id;
+        }, options?: CallOptions): Promise<Upload>;
+        putPart(input: {
+            chatId: Id;
+            uploadId: Id;
+            part: number;
+            bytes: Uint8Array;
+        }, options?: CallOptions): Promise<void>;
+        complete(input: {
+            chatId: Id;
+            uploadId: Id;
+        }, options?: CallOptions): Promise<Upload>;
+        uploadFile(input: Omit<StartUploadInput, "sizeBytes"> & {
+            source: ReplayableBytes;
+        }, options?: CallOptions & {
+            concurrency?: number;
+            onProgress?: (confirmedBytes: number) => void;
+        }): Promise<Upload>;
+    };
+    readonly content: {
+        read(input: {
+            chatId: Id;
+            contentRef: Id;
+            maxBytes: number;
+        }, options?: CallOptions): Promise<ContentDownload>;
+    };
+    /** 释放本地资源，不退出登录、不远程取消 Response。 */
+    dispose(): void;
+}
+/** 消费者可实现的小接口；扩展全量 Client 不应扩大这些接口的必需方法集。 */
+export type ChatReader = Pick<Client["chats"], "list" | "get">;
+export type MessageSender = Pick<Client["messages"], "send">;
+export type ResponseReader = Pick<Client["responses"], "get" | "subscribe">;