@zhin.js/client 1.1.3 → 1.1.5

package/README.md

@@ -1,476 +1,132 @@
-# Zhin Client - 动态页面路由与插件配置系统
+# @zhin.js/client
 
-> **本仓库目录约定（与本包对应）**  
-> - **`client/`**：浏览器端源码（路由、Redux、WebSocket 等）。  
-> - **`dist/`**：`pnpm build` 后的发布产物；`package.json` 的 `main`/`types` 指向此处。  
-> 包根目录 `packages/client/` 表示 npm 包 `@zhin.js/client`，内层 `client/` 表示「Web 客户端实现」，与 [仓库结构与模块化约定](../../docs/contributing/repo-structure.md) 中 §3.4 一致。
+Remote Console **浏览器 SDK**（entries 加载、路由/工具注册、带 Token 的 REST）。**不含 UI** — 壳层在独立仓库 [zhin-console](https://github.com/zhinjs/console)。
 
-基于 React Router 7.0 的动态页面管理系统，集成插件配置功能，支持基于 Schema 的自动表单生成。
-
-## 特性
-
-### 路由系统
-- 🌳 **树形路由结构** - 使用树形结构管理页面路由，支持任意深度的嵌套
-- ✅ **动态页面管理** - 运行时添加、删除、更新页面
-- ✅ **React Router 7.0** - 使用最新的 React Router
-- ✅ **TypeScript 支持** - 完整的类型定义
-- ✅ **WebSocket 集成** - 支持动态加载插件入口脚本
-- ✅ **Redux 状态管理** - 集成 Redux 持久化
-
-### 配置系统
-- 🔧 **Schema 驱动** - 支持 15 种 Schema 数据类型
-- 📝 **自动表单生成** - 根据 Schema 自动生成配置表单
-- 🎨 **智能 UI 组件** - 针对不同类型自动选择最佳 UI 控件
-- 🔄 **实时配置更新** - 支持配置文件的实时读取和保存
-- 🧩 **模块化设计** - 17 个独立的字段渲染器，易于扩展
+> **路径约定**：本包位于 `packages/console/client/`（npm `@zhin.js/client`）。源码在 `client/`，构建产物在 `dist/`。
 
 ## 安装
 
 ```bash
-pnpm add react-router@7.0.0 events @types/events
-```
-
-## 基本使用
-
-### 1. 设置页面路由
-
-```tsx
-// main.tsx
-import { addPage, DynamicRouter } from '@zhin.js/client'
-
-// 添加页面 - 使用 Component 而不是 element，icon 使用字符串
-addPage({
-  key: 'home',
-  path: '/',
-  title: '首页',
-  icon: 'Home',  // 图标名称对应 lucide-react 的组件名
-  Component: HomePage
-})
-
-addPage({
-  key: 'dashboard',
-  path: '/dashboard',
-  title: '仪表盘',
-  icon: 'LayoutDashboard',
-  Component: DashboardPage
-})
-
-// 渲染应用
-createRoot(document.getElementById('root')).render(
-  <Provider store={store}>
-    <PersistGate loading={null} persistor={persistor}>
-      <DynamicRouter />
-    </PersistGate>
-  </Provider>
-)
-```
-
-### 2. 页面操作
-
-```tsx
-import { addPage, removePage, updatePage } from '@zhin.js/client'
-
-// 添加页面
-addPage({
-  key: 'settings',
-  path: '/settings',
-  title: '设置',
-  icon: <Settings className="w-5 h-5" />,
-  element: <SettingsPage />
-})
-
-// 删除页面
-removePage('/settings')
-
-// 更新页面
-updatePage('/settings', {
-  key: 'settings',
-  path: '/settings',
-  title: '设置（更新）',
-  icon: <Settings className="w-5 h-5" />,
-  element: <UpdatedSettingsPage />
-})
-
-// 注：RouteMenuItem 同时支持 element（ReactNode）和 Component（ComponentType）两种属性
-
-// 向后兼容的旧 API（已废弃）
-import { addRoute, removeRoute, updateRoute } from '@zhin.js/client'
-// 这些 API 仍然可用，但推荐使用新的 addPage 等 API
-```
-
-### 3. 自动父路由查找
-
-```tsx
-// main.tsx
-import { addPage } from '@zhin.js/client'
-import { Home, Users, Settings } from 'lucide-react'
-
-// 1. 添加顶级页面
-addPage({
-  key: 'home',
-  path: '/',
-  title: '首页',
-  icon: 'Home',
-  Component: HomePage
-})
-
-addPage({
-  key: 'admin',
-  path: '/admin',
-  title: '管理',
-  Component: AdminLayout
-})
-
-// 2. 自动查找父路由：/admin/users
-// 会查找 /admin 是否存在，如果存在，插入 users 到 /admin
-addPage({
-  key: 'admin-users',
-  path: '/admin/users',
-  title: '用户管理',
-  icon: 'Users',
-  Component: UsersPage
-})
-
-addPage({
-  key: 'admin-settings',
-  path: '/admin/settings',
-  title: '系统设置',
-  icon: 'Settings',
-  Component: AdminSettingsPage
-})
-
-// 3. 自动查找父路由：/admin/users/detail
-// 会查找 /admin/users 是否存在，如果存在，插入 detail 到 /admin/users
-addPage({
-  key: 'user-detail',
-  path: '/admin/users/detail',
-  title: '用户详情',
-  Component: UserDetailPage
-})
-
-// 4. 动态添加嵌套页面
-setTimeout(() => {
-  // 会自动查找 /admin 是否存在，如果存在，插入 analytics 到 /admin
-  addPage({
-    key: 'admin-analytics',
-    path: '/admin/analytics',
-    title: '分析',
-    Component: AnalyticsPage
-  })
-}, 2000)
-
-// 5. 动态添加更深层嵌套
-setTimeout(() => {
-  // 会自动查找 /admin/analytics 是否存在，如果存在，插入 reports 到 /admin/analytics
-  addPage({
-    key: 'analytics-reports',
-    path: '/admin/analytics/reports',
-    title: '分析报告',
-    Component: ReportsPage
-  })
-}, 4000)
+pnpm add @zhin.js/client
 ```
 
-### 4. 事件监听
-
-```tsx
-import { routerManager } from '@zhin.js/client'
-
-// 监听路由变化
-routerManager.onRouteChange(() => {
-  console.log('Routes changed')
-})
-
-// 监听路由添加
-routerManager.onRouteAdd((route) => {
-  console.log('Route added:', route.path)
-})
-
-// 监听路由删除
-routerManager.onRouteRemove((path) => {
-  console.log('Route removed:', path)
-})
-```
-
-## API 参考
-
-### 页面管理 API（推荐）
-
-```tsx
-// 添加页面
-addPage(route: RouteMenuItem): void
-
-// 删除页面
-removePage(path: string): void
-
-// 更新页面
-updatePage(path: string, updates: Partial<RouteMenuItem>): void
-
-// 获取页面
-getPage(path: string): RouteMenuItem | undefined
-
-// 获取所有页面
-getAllPages(): RouteMenuItem[]
-
-// 清空所有页面
-clearPages(): void
-```
-
-### 旧 API（已废弃，保留向后兼容）
-
-```tsx
-/** @deprecated 请使用 addPage */
-addRoute(route: RouteMenuItem): void
-
-/** @deprecated 请使用 removePage */
-removeRoute(path: string): void
+Peer：`react >= 18`（`createPluginRegisterHostApi` 需要 React 引用）。
 
-/** @deprecated 请使用 updatePage */
-updateRoute(path: string, route: RouteMenuItem): void
+## 概览
 
-/** @deprecated 请使用 getPage */
-getRoute(path: string): RouteMenuItem | undefined
+| 导出 | 用途 |
+|------|------|
+| `loadConsoleEntries` | 拉 `GET /entries`、动态 import 各 entry、调用 `register(hostApi)` |
+| `createPluginRegisterHostApi` | 由壳层的 `React` / `addRoute` / `addTool` 构造 `PluginRegisterHostApi` |
+| `apiFetch` | 相对 Host API Base 的 `fetch`，自动附加 `Authorization: Bearer` |
+| `getApiBase` / `getToken` | 读取登录页写入 `localStorage` 的 API Base 与 Token |
+| `app` | 路由与工具注册单例（`addRoute`、`addTool` 等） |
+| `configureConsole` / `getRuntimeEnv` | 运行时环境（development / production） |
+| `createRegistryStore` / `useRegistry` | 可选 registry store |
+| `ENDPOINT_RPC` / `INBOX_RPC` / `SIDE_EVENT_RPC` / `SIDE_EVENT_PUSH` | `@zhin.js/console-protocol` 的规范 RPC 与推送名称 |
+| `normalizeConsolePushType` / `normalizeConsolePushMessage` | 在 SDK 边界兼容旧 `endpoint:*` 推送并输出规范事件与 payload |
+| `parseConsoleInboxEvent` | 一次完成 Inbox 推送名称、身份别名和 message/request/notice 分类 |
+| `ConsoleEndpointSummary` / `EndpointManagementCapability` | Host 与 Remote Console 共享的 Endpoint wire 类型 |
+| `fetchConsoleEventHistory` | 按 `(runtimeId, eventId)` 拉取有界事件历史 |
+| `WebSocketManager.onConsoleEvent` | 订阅带 `live/history` 投递来源的强类型事件 |
+| `WebSocketManager.onConsoleEventRecoveryGap` | 观察不可续接游标并触发领域全量重同步 |
+| `ConsoleInboxNoticesQuery` / `ConsoleInboxNoticesResult` | 以 `unreadOnly` 从持久 Inbox 重建未读通知 |
 
-/** @deprecated 请使用 getAllPages */
-getAllRoutes(): RouteMenuItem[]
-
-/** @deprecated 请使用 clearPages */
-clearRoutes(): void
-```
+类型与 Entry 契约来自 `@zhin.js/contract`。
 
-### routerManager 对象
+业务 UI 应使用 SDK 导出的协议常量和 Endpoint 类型，不要硬编码旧 `endpoint:list`、`endpoint:sendMessage` 等名称，也不要复制 `EndpointInfo`。SDK 会把旧 Host 推送别名归一化为 `message.receive` / `request.receive` / `notice.receive`，并统一 `endpointId`、`channelId` 字段。
 
-```tsx
-// 事件监听方法
-routerManager.onRouteChange(callback: () => void): () => void
-routerManager.onRouteAdd(callback: (route: RouteConfig) => void): () => void
-routerManager.onRouteRemove(callback: (path: string) => void): () => void
-routerManager.onRouteUpdate(callback: (path: string, route: RouteConfig) => void): () => void
-routerManager.onRouteClear(callback: () => void): () => void
-```
+## 启动：加载插件 Console Entry
 
-### RouteMenuItem 接口
+Remote Console 壳层在登录后调用：
 
 ```tsx
-interface RouteMenuItem {
-  key: string              // 唯一标识
-  path: string             // 路由路径
-  title: string            // 页面标题
-  icon?: ReactNode         // 图标元素（直接传入 React 元素，如 <Home className="w-5 h-5" />）
-  element?: ReactNode      // React 组件
-  children?: RouteMenuItem[]  // 子路由
-  meta?: {
-    order?: number         // 排序
-    hideInMenu?: boolean   // 是否在菜单中隐藏
-    requiresAuth?: boolean // 是否需要认证
-    [key: string]: any
-  }
-}
+import React from "react";
+import {
+  app,
+  createPluginRegisterHostApi,
+  loadConsoleEntries,
+} from "@zhin.js/client";
+
+const hostApi = createPluginRegisterHostApi({
+  React,
+  addRoute: app.addRoute.bind(app),
+  addTool: app.addTool.bind(app),
+});
+
+await loadConsoleEntries({
+  hostApi,
+  // Remote Console：Host 监听地址，用于解析 /@dev、/@assets 模块 URL
+  assetOrigin: "http://127.0.0.1:8086",
+  fetchInit: () => ({
+    headers: { Authorization: `Bearer ${localStorage.getItem("zhin_api_token")}` },
+  }),
+  onFetchError: (status) => console.error("entries fetch failed", status),
+  onEmpty: () => console.warn("no console entries"),
+});
 ```
 
-## 高级用法
+`loadConsoleEntries` 内部：`fetchConsoleEntries` → `registerConsolePluginsFromEntries` → 各 entry 模块的 `register` 或 `default.register`。
 
-### 动态页面操作
+插件 `client/` 入口示例：
 
 ```tsx
-import { addPage, updatePage, removePage } from '@zhin.js/client'
-
-// 运行时动态添加页面
-setTimeout(() => {
-  const DynamicPage = () => <div>Dynamic Page</div>
-  addPage({
-    key: 'dynamic',
-    path: '/dynamic',
-    title: '动态页面',
-    Component: DynamicPage
-  })
-}, 2000)
-
-// 动态更新页面
-setTimeout(() => {
-  const UpdatedPage = () => <div>Updated Page</div>
-  updatePage('/dynamic', {
-    key: 'dynamic',
-    path: '/dynamic',
-    title: '动态页面（已更新）',
-    Component: UpdatedPage
-  })
-}, 4000)
-
-// 动态删除页面
-setTimeout(() => {
-  removePage('/dynamic')
-}, 6000)
-```
-
-### WebSocket 动态加载
-
-```tsx
-import { useWebSocket, addPage } from '@zhin.js/client'
-
-function App() {
-  // 连接 WebSocket，接收动态入口脚本
-  const ws = useWebSocket({
-    onMessage: (message) => {
-      console.log('收到消息:', message)
-    }
-  })
-
-  return (
-    <div>
-      <p>WebSocket 状态: {ws.connected ? '已连接' : '未连接'}</p>
-      <p>已加载入口: {ws.entries.length}</p>
-      <DynamicRouter />
-    </div>
-  )
+import type { PluginRegisterHostApi } from "@zhin.js/contract";
+
+export async function register(hostApi: PluginRegisterHostApi) {
+  hostApi.addRoute({
+    path: "/my-plugin",
+    name: "My Plugin",
+    element: hostApi.React.createElement(MyPage),
+    icon: "Puzzle",
+  });
 }
-
-// 插件入口脚本示例（my-plugin-entry.ts）
-import { addPage } from '@zhin.js/client'
-
-addPage({
-  key: 'my-plugin',
-  path: '/my-plugin',
-  title: '我的插件',
-  icon: 'Puzzle',
-  Component: MyPluginPage
-})
 ```
 
-### 事件统计
+## Host API 请求
 
-```tsx
-// 路由统计
-let routeCount = 0
-routerManager.onRouteAdd(() => {
-  routeCount++
-  console.log(`Total routes: ${routeCount}`)
-})
-
-routerManager.onRouteRemove(() => {
-  routeCount--
-  console.log(`Total routes: ${routeCount}`)
-})
-```
+登录页将 API Base 与 Token 存入 `localStorage`（键 `zhin_api_base`、`zhin_api_token`）。业务请求使用 `apiFetch`：
 
-### 条件事件监听
+```ts
+import { apiFetch } from "@zhin.js/client";
 
-```tsx
-// 只监听特定路径的路由变化
-routerManager.onRouteAdd((route) => {
-  if (route.path.startsWith('/admin')) {
-    console.log('Admin route added:', route.path)
-  }
-})
+const res = await apiFetch("/api/console/request", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ method: "system.status", params: {} }),
+});
 ```
 
-## 插件配置系统
-
-### Schema 支持的数据类型
-
-Zhin Client 配置系统完整支持所有 15 种 Schema 数据类型：
-
-#### 基础类型
-- `string` - 字符串（支持枚举/多行/单行）
-- `number` / `integer` - 数字（支持 min/max 限制）
-- `boolean` - 布尔值（开关控件）
+401 时清除 Token 并派发 `zhin:auth-required`。
 
-#### 特殊类型
-- `percent` - 百分比（滑块 + 数字输入）
-- `date` - 日期（日期选择器）
-- `regexp` - 正则表达式（带验证）
-- `const` - 常量（只读显示）
+辅助：`resolveApiUrl`、`resolveWebSocketUrl`（SSE `/api/events` 等）。
 
-#### 集合类型
-- `list` - 列表（支持嵌套）
-- `tuple` - 元组（固定字段）
-- `object` - 对象（嵌套结构）
-- `dict` - 字典（JSON 编辑器）
+Client 在连接 `/api/events` 前先补拉 `/api/events/history`，再携带最新游标进入 SSE；Host 会原子重放 HTTP 与订阅之间产生的事件。游标只在 Inbox 持久化成功后推进，重复的 history/live 投递按 `(runtimeId, eventId)` 幂等写入 IndexedDB。`gap` 不会被吞掉，页面可订阅恢复缺口并改走领域 HTTP 全量投影。
 
-#### 组合类型
-- `union` - 联合类型（多选一）
-- `intersect` - 交叉类型（满足所有）
+## `createPluginRegisterHostApi`
 
-#### 通用类型
-- `any` - 任意类型（JSON 编辑器）
-- `never` - 永不类型（警告提示）
+将壳层已有的 React 与路由/工具注册函数适配为契约中的 `PluginRegisterHostApi`（含 `addPage` 别名 → `addRoute`）：
 
-### 使用插件配置组件
+```ts
+import { createPluginRegisterHostApi } from "@zhin.js/client";
 
-```tsx
-import PluginConfigForm from '@zhin.js/client/components/PluginConfigForm'
-
-<PluginConfigForm
-  pluginName="my-plugin"
-  onClose={() => setDialogOpen(false)}
-  onSuccess={() => refetchPlugin()}
-/>
+const hostApi = createPluginRegisterHostApi({ React, addRoute, addTool });
 ```
 
-### 定义插件配置 Schema
-
-```typescript
-import { Schema } from 'zhin.js'
-
-export const config = Schema.object({
-  // 基础类型
-  name: Schema.string('插件名称').required(),
-  enabled: Schema.boolean('是否启用').default(true),
-  port: Schema.number('端口').min(1).max(65535).default(3000),
-  
-  // 特殊类型
-  opacity: Schema.percent('透明度').default(0.8),
-  startDate: Schema.date('开始日期'),
-  pattern: Schema.regexp('匹配模式'),
-  
-  // 集合类型
-  tags: Schema.list(Schema.string(), '标签'),
-  server: Schema.object({
-    host: Schema.string().default('localhost'),
-    port: Schema.number().default(3000)
-  }),
-  
-  // 组合类型
-  mode: Schema.union([
-    Schema.const('auto'),
-    Schema.const('manual')
-  ])
-})
-```
+## 低级 API
 
-### 配置表单特性
+- `fetchConsoleEntries(options?)` — 仅拉 JSON，不 import
+- `registerConsolePluginsFromEntries(entries, hostApi, ...)` — 已知 entries 列表时注册
+- `getRegisterFn(mod)` — 从动态模块解析 `register` 导出
 
-- **自动渲染**: 根据 Schema 类型自动选择合适的 UI 组件
-- **智能分组**: 简单字段直接展示，复杂字段可折叠
-- **嵌套支持**: 完整支持任意深度的嵌套结构
-- **实时验证**: 输入时进行类型验证和格式检查
-- **紧凑布局**: 使用 ScrollArea 和 Accordion 优化空间使用
+## 构建
 
-## 组件架构
-
-### PluginConfigForm 模块结构
-
-```
-PluginConfigForm/
-├── types.ts                      - 类型定义
-├── BasicFieldRenderers.tsx       - 基础类型渲染器 (9个)
-├── CollectionFieldRenderers.tsx  - 集合类型渲染器 (5个)
-├── CompositeFieldRenderers.tsx   - 组合类型渲染器 (2个)
-├── FieldRenderer.tsx             - 字段渲染器主入口
-├── NestedFieldRenderer.tsx       - 嵌套字段渲染器
-└── index.tsx                     - 主组件
+```bash
+pnpm --filter @zhin.js/client build
 ```
 
-17 个独立渲染器，职责单一，易于测试和扩展。
-
-## 注意事项
-
-1. **路由路径唯一性** - 确保路由路径的唯一性，避免冲突
-2. **事件清理** - 记得清理事件监听器，避免内存泄漏
-3. **性能考虑** - 大量路由时考虑使用懒加载
-4. **类型安全** - 使用 TypeScript 确保类型安全
-5. **Schema 定义** - 为插件配置定义清晰的 Schema，提供友好的描述信息
-
-## 示例项目
+## 相关文档
 
-查看 `app/src/main.tsx` 中的完整示例。
+- [Remote Console 使用说明](../../../docs/console-remote.md)
+- [Console 栈概览](../README.md)
+- [@zhin.js/host-http（Console/HTTP Host 传输）](../../host/http/README.md)

package/client/agent-stream.ts

@@ -0,0 +1,121 @@
+import {
+  AGENT_STREAM_MEDIA_TYPE,
+  ZHIN_AGENT_SESSION_API_PREFIX,
+  ZHIN_SESSION_ID_HEADER,
+  foldAgentStreamNdjson,
+  iterateAgentStreamNdjson,
+  type AgentStreamEvent,
+  type AgentStreamReduceState,
+  type ContinueAgentSessionResponse,
+  type FoldAgentStreamOptions,
+  type StartAgentSessionResponse,
+} from "@zhin.js/contract";
+import { getToken, resolveApiUrl } from "./console-utils/remoteApi.js";
+
+export type AgentStreamClientOptions = {
+  fetch?: typeof fetch;
+};
+
+function resolveFetch(options?: AgentStreamClientOptions): typeof fetch {
+  const impl = options?.fetch ?? globalThis.fetch;
+  if (!impl) throw new Error("fetch is not available");
+  return impl;
+}
+
+async function authedFetch(
+  path: string,
+  init: RequestInit,
+  fetchImpl: typeof fetch,
+): Promise<Response> {
+  const token = getToken();
+  const headers = new Headers(init.headers);
+  if (token) headers.set("Authorization", `Bearer ${token}`);
+  const url = path.startsWith("/") ? resolveApiUrl(path) : path;
+  const res = await fetchImpl(url, { ...init, headers });
+  if (res.status === 401 && typeof localStorage !== "undefined") {
+    sessionStorage.removeItem("zhin_api_token");
+    localStorage.removeItem("zhin_api_token");
+    window.dispatchEvent(new CustomEvent("zhin:auth-required"));
+  }
+  return res;
+}
+
+async function readJson<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(err.error ?? `HTTP ${res.status}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+/** POST /zhin/v1/session — start a Host agent session turn. */
+export async function startAgentSession(
+  message: string,
+  options?: AgentStreamClientOptions,
+): Promise<StartAgentSessionResponse> {
+  const fetchImpl = resolveFetch(options);
+  const res = await authedFetch(`${ZHIN_AGENT_SESSION_API_PREFIX}/session`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ message }),
+  }, fetchImpl);
+  return readJson<StartAgentSessionResponse>(res);
+}
+
+/** POST /zhin/v1/session/:sessionId — continue with continuationToken + message. */
+export async function continueAgentSession(
+  sessionId: string,
+  continuationToken: string,
+  message: string,
+  options?: AgentStreamClientOptions,
+): Promise<ContinueAgentSessionResponse> {
+  const fetchImpl = resolveFetch(options);
+  const res = await authedFetch(
+    `${ZHIN_AGENT_SESSION_API_PREFIX}/session/${encodeURIComponent(sessionId)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ continuationToken, message }),
+    },
+    fetchImpl,
+  );
+  return readJson<ContinueAgentSessionResponse>(res);
+}
+
+export type SubscribeAgentStreamOptions = FoldAgentStreamOptions & {
+  startIndex?: number;
+  fetch?: typeof fetch;
+  onEvent?: (event: AgentStreamEvent, state: AgentStreamReduceState) => void;
+};
+
+/** GET /zhin/v1/session/:sessionId/stream — consume NDJSON until the stream closes. */
+export async function subscribeAgentStream(
+  sessionId: string,
+  options?: SubscribeAgentStreamOptions,
+): Promise<AgentStreamReduceState> {
+  const fetchImpl = resolveFetch(options);
+  const startIndex = options?.startIndex ?? 0;
+  const query = startIndex > 0 ? `?startIndex=${startIndex}` : "";
+  const res = await authedFetch(
+    `${ZHIN_AGENT_SESSION_API_PREFIX}/session/${encodeURIComponent(sessionId)}/stream${query}`,
+    {
+      method: "GET",
+      headers: { Accept: AGENT_STREAM_MEDIA_TYPE },
+    },
+    fetchImpl,
+  );
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(err.error ?? `HTTP ${res.status}`);
+  }
+  const headerSessionId = res.headers.get(ZHIN_SESSION_ID_HEADER);
+  if (headerSessionId && headerSessionId !== sessionId) {
+    throw new Error(`stream session id mismatch: ${headerSessionId}`);
+  }
+  if (!res.body) {
+    throw new Error("stream response has no body");
+  }
+  return foldAgentStreamNdjson(res.body, options);
+}
+
+export { iterateAgentStreamNdjson, foldAgentStreamNdjson };