dsh-bailinghub 0.3.0 → 0.4.0

package/docs/README.zh-CN.md

@@ -2,220 +2,144 @@
 
 [English](../README.md) | 简体中文
 
-把商城、SaaS 或其他业务系统接到 BailingHub 后，本地 DeepSeek Harness 智能体就能直接操作
-它们的后台：查询数据、修改资料，或者执行系统已经开放的其他操作。实际能做什么仍由当前业务
-账号权限和审批规则决定，执行过程也会记录在 BailingHub 中。
+让本地 DeepSeek Harness 智能体操作已经接入 BailingHub 的业务系统：查询记录、修改允许的字段，
+需要审批时继续走原有规则。BailingHub 会记录用了哪份授权、做了什么，以及业务系统返回的结果。
 
-具体能做什么取决于业务系统开放了哪些能力，例如：
+**0.4.0 支持在一个会话中使用同一系统的多份授权。** 例如，分别授权 A 店和 B 店后，新建会话并
+选中两者，就可以说：
 
-- 查询订单、客户、商品或员工资料；
-- 修改允许编辑的字段或业务状态；
-- 完成其他已经授权的后台操作；
-- 把结果返回到本地对话，同时在 BailingHub 中保留对应的工具步骤。
+> 对比今天 A 店和 B 店的营业情况，按门店分别说明。
 
-思考、工具选择与编排留在本地 DSH；BailingHub 负责向本地智能体提供已授权的业务上下文、
-可用能力、审批状态、调用恢复与审计记录。
+智能体会为每次调用选择对应授权，不需要你反复切换当前连接。具体能查什么、能改什么，仍取决于
+业务系统开放的能力和各账号权限。本版尚不提供不同系统或不同路由之间的编排。
 
-这是独立社区集成，不是 DeepSeek 官方开发、认证、合作、背书或推荐的插件。
+本版也能把可见沟通过程与业务操作关联起来。记录上传失败后，可以在联网或重启后继续补传，
+不会因此重新执行业务操作。
 
-> **当前稳定版本线：**`dsh-bailinghub@0.3.0` 使用下文说明的原生 Agent Client 流程。
-> 公开 `0.1.1` 仅作为明确的静态 MCP 兼容路径继续保留。
+这是独立社区集成，不是 DeepSeek 官方开发、认证、合作、背书或推荐的插件。
 
-希望用最短路径完成首次使用，可以直接阅读[三分钟开始使用](GETTING_STARTED.zh-CN.md)。
+## 安装与开始使用
 
-## 0.3 Agent Client 的关系
+需要 Node.js `22.19.0+` 或 `24+`、pnpm，以及兼容的 DeepSeek Harness。管理员应先完成业务系统
+接入。配套版本为 **BailingHub Core 0.6.1 → BailingHub MCP/SDK 0.4.0 → 本插件 0.4.0**。
 
-```text
-DeepSeek Harness 本地智能体
-  -> dsh-bailinghub 原生 Cordis 适配器
-  -> bailinghub-mcp-server/sdk
-  -> BailingHub Agent Auth + Agent API
-  -> 部署者选择的业务接入与最终业务授权
+```bash
+npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile web add dsh-bailinghub@0.4.0
 ```
 
-各层职责保持独立：
-
-- **BailingHub Core** 负责 Agent Auth、可信业务身份、运行时上下文、知识库与记忆投影、
-  能力治理、审批、调用状态和审计记录。
-- **`bailinghub-mcp-server/sdk`** 负责浏览器登录、PKCE、凭据存储与刷新，以及按
-  Hub/client/workspace 选择连接和映射 HTTP DTO。
-- **`dsh-bailinghub`** 只负责 DSH 会话、提示词、命令和动态工具生命周期，不保存凭据，
-  也不直接调用业务 API。
-
-Agent Client 不是 BailingHub 现有的“执行器”。执行器接收中枢任务并处理必须靠近某台机器
-完成的工作；Agent Client 则把交互式思考与编排循环放在用户本地 DSH 智能体中。
+插件会自动安装精确依赖 `bailinghub-mcp-server@0.4.0`，无需另装 SDK。
+已经使用旧版的用户请先看[0.3 到 0.4 的迁移步骤](MIGRATION_VNEXT.md)。
 
-## 安装前准备
+按照[开始使用指南](GETTING_STARTED.zh-CN.md)填写管理员提供的四项公开连接信息，再到浏览器授权。
+不要把业务密码、Client Token、签名密钥或模型 Key 填进插件设置或聊天消息。
 
-部署者和业务接入开发者需要先在自己的 BailingHub 中准备这些公开标识：
+## 为每个会话选择账号
 
-1. 一套可访问的 HTTPS BailingHub，并部署匹配版本的 Agent Auth 与 Agent API；
-2. 一个公开 Agent Client 应用标识 `clientAppId`；
-3. 至少一个允许授权的 workspace；在 Agent Client v1 中，workspace id 就是
-   BailingHub route id；
-4. 在中枢 Client App 上配置一个稳定且不绑定具体账号、租户的业务授权入口，并在该 route
-   后方接通受治理的 ACC/Tool Provider 能力。登录、切换账号和选择租户都由业务授权页完成。
+在原业务授权页面分别授权 A 店和 B 店。创建连接时使用清晰的本机名称，例如 `A 店`、`B 店`，
+并在授权页核对实际业务身份。名称是你提供的标签，不证明身份，也不授予权限；`default`、
+`default-2` 无法让智能体知道你指的是哪家店。
 
-最终用户**不需要**在插件中填写业务 API 地址、业务账号密码、Tool Provider 签名密钥、
-BailingHub Client Token 或模型提供方 Key。
+**新建会话，在发送第一条消息前**执行：
 
-## 安装 0.3 版本线
-
-前置条件：
-
-- Node.js `22.19.0+` 或 `24+`；
-- `pnpm` 与兼容矩阵中列出的 DeepSeek Harness 版本；
-- 已完成上面的 BailingHub 接入准备。
-
-将精确稳定版本安装到 DSH Web Profile：
-
-```bash
-npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.3.0
+```text
+/bailinghub connections list
+/bailinghub scope set <A店连接键> <B店连接键>
+/bailinghub scope
 ```
 
-`dsh-bailinghub@0.3.0` 会自动安装精确兼容的 `bailinghub-mcp-server@0.3.0` 依赖。
-DSH 用户不应该再自行猜测或单独安装某个 SDK 版本。
+把占位符换成列表里的固定连接键，不是连接名称。也可以只选一份授权；多份授权必须属于同一个
+中枢、Client App 和 workspace。等待设置成功回显后，再发送业务请求。
 
-## 配置一个中枢连接
+**新会话默认是普通聊天，选择业务范围后才会提供业务工具。** 登录成功或切换默认连接不会自动
+开启业务访问。`/bailinghub scope none` 可显式选择普通聊天。第一条用户消息会固定这个范围；
+之后要增减账号，或从普通聊天改成业务会话，都需要新建会话。
 
-原生插件只有四个宿主配置字段：
+同一套能力不必为每家店重复声明。智能体选择每次调用使用的授权，不会拿到凭据；各项操作仍受
+对应账号权限和审批规则约束。需要审批时，在会话仍运行的情况下，继续的是原调用。
 
-| 插件字段 | 环境变量 | 含义 | 是否 Secret |
-| --- | --- | --- | --- |
-| `hubUrl` | `BAILINGHUB_HUB_URL` | 开发者自己部署的 BailingHub 公共 HTTPS 地址 | 否 |
-| `clientAppId` | `BAILINGHUB_CLIENT_APP_ID` | 在该中枢注册的公共 Agent Client 应用标识 | 否 |
-| `workspace` | `BAILINGHUB_WORKSPACE` | 初始已授权 workspace/route id | 否 |
-| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | 用户选择的本机连接名称 | 否 |
+任意一份选中授权撤销、被替换或暂时无法核验时，整个会话的业务访问暂停，不会偷偷改用其他账号。
+临时断网可以在联网后重试原范围；已确认的撤销或身份变化，需要新建会话并选择有效授权。
 
-使用中性占位值的示例：
+## 查看沟通过程与操作结果
 
-```bash
-export BAILINGHUB_HUB_URL='https://hub.example.com'
-export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
-export BAILINGHUB_WORKSPACE='order_assistant'
-export BAILINGHUB_CONNECTION_NAME='default'
+配合 Core 0.6.1 和 SDK 0.4.0，BailingHub 可以把可见的用户消息、助手回复、轮次，以及原业务
+执行记录的关联放在同一份会话记录中。各份授权仍保留自己的业务调用记录，汇总回答不会复制到
+每个账号的记忆中。
+
+```text
+/bailinghub archive status
+/bailinghub archive sync
 ```
 
-也可以通过 DSH 的插件设置界面填写同样四个字段。不要在 Cordis Patch 中增加 Token、授权
-页面地址、业务域名或任何凭据。中枢会根据 Client App 找到唯一业务授权入口。
-`connectionName` 只是用户控制的本机连接选择器，不是账号、租户或身份声明。
+`archive status` 查看沟通记录是否已上传；`archive sync` 补传已保存记录，不重做业务操作。
+它与 `/bailinghub sync` 不同：后者只重试当前运行中会话的待同步执行结尾记录。
 
-启动前检查最终合成配置：
+| 状态 | 含义 |
+| --- | --- |
+| `synced` | 已保存事件已获中枢确认，不代表业务操作成功 |
+| `pending` | 还没传完，恢复连接后可以重试 |
+| `blocked` | 原授权核验阻止上传，可用 `/bailinghub scope` 查看 |
+| `unsupported` | 当前 SDK 或中枢不支持这套归档契约 |
+| `storage_error` | 本地写入失败，部分可见消息可能尚未安全保存 |
+| `recovery_gap` | 对照 DSH 历史发现归档缺失，记录不完整 |
 
-```bash
-dsh --profile web --dump-config
-dsh web
-```
+重开已保存的业务会话时，必须核验全部原授权后才恢复原范围。离线重开后，可以联网并在**同一
+会话**执行 `/bailinghub archive sync` 或 `/bailinghub scope` 重试核验。这恢复的是范围与
+已保存记录的补传，**不恢复进程重启前的业务调用、待审批操作或未完成任务**。未开始的已保存
+草稿需要重新选择；没有有效旧范围快照的已开始会话不能自动采用今天的默认账号。
 
-## 浏览器授权与使用
+## 哪些信息会共享和保存
 
-在 DSH 中依次执行：
+选中账号的业务上下文与可见用户请求会进入同一个本地智能体及模型会话。合并后的沟通归档按完整
+授权集合控制访问，仅有其中一份授权不能读取混合会话。若这些账号的数据需要彼此隔离，应使用
+不同会话。
 
-```text
-/bailinghub login
-/bailinghub doctor
-/bailinghub status
-/bailinghub workspaces
-```
+采集从本版启用后的业务轮次开始，只包含可见文本，不包含附件、隐藏思考或全部历史会话，也不会
+自动清除用户粘贴在正文里的秘密。检测到历史缺口会明确显示；宿主不提供持久历史时，覆盖度为
+`unverified`，不会声称完整。
 
-`login` 会在系统浏览器打开中枢管理员配置的唯一业务授权入口。业务授权页负责登录、切换账号、
-选择租户，并确认最终业务身份和申请的 workspace，然后返回受 `state` 与 PKCE S256 保护的
-随机回环回调。Access Token 与 Refresh Token 只进入 SDK 所有的安全存储，不会写入插件配置，
-也不会由命令输出。
+本机私有待上传记录含有**明文任务正文**，已上传的事件也会保留，直到宿主或用户自行清理；目前
+没有自动保留期限。删除本机记录不等于删除中枢记录。授权凭据仍由 SDK 安全存储。启用业务访问前
+请阅读[隐私说明](../PRIVACY.md)与[安全策略](../SECURITY.md)。
 
-常用命令：
+## 常用管理命令
 
 | 命令 | 用途 |
 | --- | --- |
-| `/bailinghub doctor` | 在不输出凭据的前提下检查宿主 API、公开配置、SDK、授权状态和 workspace 连通性 |
-| `/bailinghub connections list` | 查看本机公开连接元数据与授权状态，不输出 Token |
-| `/bailinghub connections add <名称> <中枢地址> <clientAppId> <workspace>` | 创建并选择另一个本机连接实例；公开绑定可以与已有实例相同 |
-| `/bailinghub connections use <名称或连接键>` | 只为之后新建的会话选择一个已登记连接 |
-| `/bailinghub connections remove <名称或连接键>` | 先远程撤销 Agent Session，再删除本机凭据和公开元数据 |
-| `/bailinghub login` | 在浏览器授权当前 Hub/client/workspace |
-| `/bailinghub status` | 查看当前连接状态，但不输出凭据 |
-| `/bailinghub workspaces` | 查看当前业务授权允许使用的 workspace |
-| `/bailinghub use <workspace>` | 为新会话切换到另一个已授权 workspace |
-| `/bailinghub sync` | 重试同步待处理的可见回复，不重复业务工具调用 |
+| `/bailinghub doctor` | 检查配置、SDK、授权及 workspace，不输出凭据 |
+| `/bailinghub login` | 在浏览器授权当前连接 |
+| `/bailinghub status` | 查看当前连接的授权状态 |
+| `/bailinghub connections list` | 查看连接名称、固定连接键和授权状态 |
+| `/bailinghub connections add <名称> <中枢地址> <clientAppId> <workspace>` | 创建并选择一个待管理的连接；含空格的名称加引号 |
+| `/bailinghub connections use <名称或连接键>` | 选择要管理或授权的连接，不改变已有会话范围 |
+| `/bailinghub connections remove <名称或连接键>` | 先撤销远端 Agent Session，再删除本机凭据 |
+| `/bailinghub workspaces` | 查看当前授权允许的 workspace |
+| `/bailinghub use <workspace>` | 为连接管理切换到另一已授权 workspace |
 | `/bailinghub logout` | 撤销并删除当前 Agent Session |
 
-插件四字段是启动连接。其他连接可用 `connections add` 登记；BailingHub 控制台“智能体客户端”
-页面也能生成同样的不含秘密命令。重启后，适配器会在第一个新 Agent 会话或用户命令前读取 SDK
-registry，并采用其中当前连接的公开元数据；registry 缺失或不可用时安全回退到这四个启动字段。
-连接名含空格时需要加引号。执行 `connections use` 后，如果该绑定尚未授权，再执行
-`/bailinghub login`。
-
-连接选择只能由用户斜杠命令发起，不会作为模型工具暴露。切换只影响之后创建的 Agent 会话，已有
-会话继续固定在原连接与 workspace。`/bailinghub use <workspace>` 是另一件事：只有当前 Agent
-Session 已经允许目标 workspace 时才成功。
-
-删除当前连接后，适配器会读取 SDK registry，把剩余的当前连接（包括没有别名的连接）设为新会话
-默认值；删除最后一个连接后则明确进入未配置状态。删除后的 registry 刷新失败不会把已经成功的
-删除改写成错误；如果删除的是非当前连接，刷新不可用时也会保留仍然有效的默认连接。
-
-对于同一个 `Hub + clientAppId + workspace` 公开绑定，最终身份由业务授权页及其可信
-`on_behalf_of` 结果决定。如果另一个本机连接名已经授权同一身份，SDK 会用本次连接覆盖旧连接，
-并撤销旧 Agent Session；不同可信身份则继续作为相互独立的连接。如果从一个已经属于其他身份的
-`connectionName` 发起登录，SDK 会保留原连接名及其 Session，为新身份分配一个不冲突的本机名称
-（例如 `default-2`），并把新连接设为后续会话的当前选择。用户可以用 `connections list` 查看
-两者，再用 `connections use <名称或连接键>` 显式切换。如果登录结果返回
-`cleanupRequired: true`，说明新连接仍然授权成功，但一个或多个同绑定旧连接还需要显式清理；
-如果身份检查被推迟，此时还不能断言它们是同一身份。不要重复授权；先查看 `connections list`，
-再对提示的旧连接执行
-`/bailinghub connections remove <名称或连接键>`。
-
-首次验收时，新建一个 DSH 会话，先做一次只读查询，再做一次允许的修改。确认 BailingHub
-后台能看到同一个会话、run、可见最终回复和工具调用轨迹。需要审批的能力必须在审批后恢复
-原 invocation，不能生成替代业务调用。
-
-本版本在 DSH Code Mode 下会明确降级，因为当前 Code Mode 无法安全呈现本轮动态 Schema。
-需要执行受治理业务操作时应使用 Native Tool Mode。
-
-## 安全与隐私边界
-
-- 模型不能通过工具参数选择 Hub URL、workspace、本机连接、业务身份、凭据、审批结论或能力版本；
-- SDK 在 macOS 使用 Keychain；Windows 凭据文件保存在 LocalAppData 并由 CurrentUser DPAPI
-  保护，Windows PowerShell 或 DPAPI 不可用时失败关闭，不会降级为明文；Linux 与其他 POSIX
-  系统必须显式启用安全文件回退；
-- BailingHub 对每次治理调用重新校验身份、scope、审批、幂等与调用状态，业务系统仍执行
-  最终权限判断；
-- 适配器会发送 Agent Client 契约所需的可见用户输入、受治理工具参数/结果和可见最终回复，
-  但不会上传隐藏思考片段；
-- 本插件只治理它注册的 BailingHub 工具，不会拦截 DSH 其他工具或模型提供方流量。
-
-生产使用前请阅读[安全策略](../SECURITY.md)、[隐私说明](../PRIVACY.md)、
-[Agent Client 契约](AGENT_CLIENT_CONTRACT.md)和[兼容范围](COMPATIBILITY.md)。
-
-## 公开 0.1.x 静态兼容模式
-
-公开 `dsh-bailinghub@0.1.1` 仍是不可变的纯配置 Bundle。它通过 DSH 内置 MCP Client 启动
-`bailinghub-mcp-server@0.1.1`，把运营者提供的一个 Client Token 固定绑定到一个 route，
-并由 BailingHub 完成编排。
-
-```bash
-dsh plugin --profile web add dsh-bailinghub@0.1.1
+连接管理与范围选择都是用户命令，不是模型工具。再次授权同一可信身份会替换旧连接和旧 Agent
+Session；不同身份独立保留。若登录提示需要清理，新连接已经授权成功，应检查提示的旧条目并重试
+删除，不要再次授权。详情见[身份与连接规则](AGENT_CLIENT_CONTRACT.md#browser-identity-and-local-reconciliation)。
 
-export BAILINGHUB_BASE_URL='https://hub.example.com'
-export BAILINGHUB_CLIENT_TOKEN='replace-with-a-route-scoped-client-token'
-export BAILINGHUB_ROUTE='order_assistant'
-```
+## 给接入开发者
 
-它只暴露三个固定工具：
+DSH 负责思考与工具编排；BailingHub Core 负责可信身份、治理、审批、调用状态和审计；SDK 负责
+浏览器授权、安全凭据和 HTTP 映射。本插件只适配 DSH 的会话、提示词、命令、工具和可见事件，
+不直接调用业务 API，也不治理其他 DSH 工具。
 
-```text
-mcp__bailinghub__submit_governed_job
-mcp__bailinghub__get_governed_job
-mcp__bailinghub__wait_for_governed_job
-```
+业务系统继续声明原有能力，为每个身份分别授权即可。自定义 DSH 宿主需接入[范围选择与恢复 API](AGENT_CLIENT_CONTRACT.md#host-owned-session-scope-api)，
+在首条消息前显示确认；原生斜杠命令已经使用这些 API。参数结构、持久化和恢复细节见
+[Agent Client 契约](AGENT_CLIENT_CONTRACT.md)。
 
-0.3 Agent Client 不会自动读取或迁移 0.1 Client Token。测试升级或回滚时必须显式固定版本，
-并遵循 [0.1 到 0.3 的迁移边界](MIGRATION_VNEXT.md)。
+请使用 Native Tool Mode。DSH Code Mode 无法安全呈现本轮动态工具结构，因此明确降级。
+版本范围见[兼容矩阵](COMPATIBILITY.md)。
 
-## 兼容范围与反馈
+## 旧版 0.1.1 与反馈
 
-0.3.0 只对 [COMPATIBILITY.md](COMPATIBILITY.md) 中列出的版本完成了验证。DeepSeek
-Harness 仍是 Developer Preview，每次 Harness 升级都必须重新执行 Native Lifecycle Smoke。
+公开 `dsh-bailinghub@0.1.1` 继续作为独立的静态 MCP 兼容路径：它启动
+`bailinghub-mcp-server@0.1.1`，使用运营者提供的固定路由 Client Token，由 BailingHub 编排。
+0.4.0 不会读取或转换该凭据。使用旧路径时继续固定旧版本，并参考[迁移说明](MIGRATION_VNEXT.md)。
 
-问题请提交到 [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues)。
-请勿附带 Token、私有部署地址、个人信息或生产业务数据。
+问题请提交到 [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues)，提供版本与
+脱敏错误，不附带 Token、私有地址、个人信息或生产业务数据。兼容测试与下载量不代表生产采用。

package/lib/authorizations.js

@@ -0,0 +1,61 @@
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]))
+  }
+  return value
+}
+
+/** A declaration can be shared; its authorization, run and revision cannot. */
+export function declarationKey(tool) {
+  return JSON.stringify(canonical(tool))
+}
+
+export function sharedDeclarations(targets, limit, preferredNames = []) {
+  const grouped = new Map()
+  const conflicts = new Set()
+  for (const target of targets) {
+    const run = target.currentRun
+    if (run?.status !== 'active') continue
+    for (const tool of run.activeTools) {
+      const key = declarationKey(tool)
+      const existing = grouped.get(tool.name)
+      if (existing && existing.key !== key) conflicts.add(tool.name)
+      if (!existing) grouped.set(tool.name, { tool, key, targets: [] })
+      grouped.get(tool.name).targets.push(target)
+    }
+  }
+  const priority = new Map(preferredNames.map((name, index) => [name, index]))
+  const tools = [...grouped.values()].filter(({ tool }) => !conflicts.has(tool.name))
+    .sort((a, b) => (priority.get(a.tool.name) ?? Infinity) - (priority.get(b.tool.name) ?? Infinity))
+  return { tools: tools.slice(0, limit), conflicts: [...conflicts].sort(), omitted: Math.max(0, tools.length - limit) }
+}
+
+export function authorizationEnvelope(tool, refs) {
+  return {
+    type: 'object',
+    properties: {
+      authorization_ref: {
+        type: 'string', enum: refs,
+        description: 'Use the authorization matching the user\'s intended account. Ask when the target is ambiguous.',
+      },
+      arguments: structuredClone(tool.parameters),
+    },
+    required: ['authorization_ref', 'arguments'],
+    additionalProperties: false,
+  }
+}
+
+export function unwrapAuthorization(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    Object.keys(value).some((key) => key !== 'authorization_ref' && key !== 'arguments') ||
+    typeof value.authorization_ref !== 'string' || !value.arguments ||
+    typeof value.arguments !== 'object' || Array.isArray(value.arguments)) {
+    throw new TypeError('An authorization_ref and an object of business arguments are required')
+  }
+  return { ref: value.authorization_ref, arguments: structuredClone(value.arguments) }
+}
+
+export function authorizedResult(target, result) {
+  return { authorization_ref: target.authorization.ref, authorization_label: target.authorization.label, result }
+}

package/lib/conversation-archive-store.js

@@ -0,0 +1,265 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+const SCHEMA = 'bailing.agent-conversation-outbox.v1'
+const MAX_BYTES = 32 * 1024 * 1024
+const LOCK_TIMEOUT_MS = 1_000
+const SECRET_KEYS = new Set(['token', 'accesstoken', 'refreshtoken', 'password', 'clientsecret', 'authorization', 'credential', 'credentials'])
+
+function storeError(code = 'ARCHIVE_STORE_UNAVAILABLE') {
+  const error = new Error(code === 'ARCHIVE_STORE_CONFLICT'
+    ? 'The conversation archive changed or is being saved. Read it again before retrying.'
+    : 'The conversation archive store is unavailable. The archive was not safely saved.')
+  error.code = code
+  return error
+}
+
+function safeError(error) {
+  return ['ARCHIVE_STORE_CONFLICT', 'ARCHIVE_STORE_UNAVAILABLE'].includes(error?.code)
+    ? error : storeError()
+}
+
+function sessionKey(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId.length || sessionId.length > 4_096) throw storeError()
+  return createHash('sha256').update(sessionId).digest('hex')
+}
+
+// The archive coordinator owns the event schema. This boundary additionally refuses
+// non-JSON values and credential fields so stores cannot become credential caches.
+function snapshotJson(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return value
+  if (!value || typeof value !== 'object' || seen.has(value)) throw storeError()
+  const array = Array.isArray(value)
+  if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw storeError()
+  seen.add(value)
+  try {
+    const entries = Reflect.ownKeys(value).filter((key) => !array || key !== 'length')
+    if (array && (entries.length !== value.length || entries.some((key, index) => key !== String(index)))) throw storeError()
+    const copy = array ? [] : {}
+    for (const key of entries) {
+      const property = Object.getOwnPropertyDescriptor(value, key)
+      if (typeof key !== 'string' || !property.enumerable || !Object.hasOwn(property, 'value') ||
+        SECRET_KEYS.has(key.replace(/[_-]/gu, '').toLowerCase()) || ['__proto__', 'constructor', 'prototype'].includes(key)) throw storeError()
+      copy[key] = snapshotJson(property.value, seen)
+    }
+    return copy
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function snapshotRecord(sessionId, record) {
+  const copy = snapshotJson(record)
+  if (!copy || Array.isArray(copy) || copy.schema !== SCHEMA || copy.sessionId !== sessionId ||
+    !Number.isSafeInteger(copy.revision) || copy.revision < 1) throw storeError()
+  if (Buffer.byteLength(JSON.stringify(copy)) > MAX_BYTES) throw storeError()
+  return copy
+}
+
+function nextRecord(sessionId, record, expectedRevision) {
+  sessionKey(sessionId)
+  if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)) throw storeError()
+  const copy = snapshotRecord(sessionId, record)
+  if (copy.revision !== (expectedRevision ?? 0) + 1) throw storeError()
+  return copy
+}
+
+function assertRevision(current, expectedRevision) {
+  if ((current?.revision ?? null) !== expectedRevision) throw storeError('ARCHIVE_STORE_CONFLICT')
+}
+
+function assertOwned(stat, kind) {
+  if (!(kind === 'directory' ? stat.isDirectory() : stat.isFile()) ||
+    (kind === 'file' && stat.nlink !== 1) ||
+    (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
+    (process.platform !== 'win32' && (stat.mode & 0o777) !== (kind === 'directory' ? 0o700 : 0o600))) throw storeError()
+}
+
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino
+}
+
+function defaultDirectory() {
+  const configured = process.env.DSH_HOME
+  const base = typeof configured === 'string' && configured.trim() ? configured : join(homedir(), '.dsh')
+  const expanded = base === '~' ? homedir() : /^~[/\\]/u.test(base) ? join(homedir(), base.slice(2)) : base
+  return join(resolve(expanded), 'plugins', 'dsh-bailinghub', 'conversation-outbox')
+}
+
+async function ensureDirectory(directory, create) {
+  if (create) await mkdir(directory, { recursive: true, mode: 0o700 })
+  let stat
+  try {
+    stat = await lstat(directory)
+  } catch (error) {
+    if (!create && error.code === 'ENOENT') return false
+    throw error
+  }
+  assertOwned(stat, 'directory')
+  return true
+}
+
+async function readRecord(path, sessionId) {
+  let before
+  try {
+    before = await lstat(path)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  assertOwned(before, 'file')
+  if (before.size > MAX_BYTES) throw storeError()
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const opened = await file.stat()
+    assertOwned(opened, 'file')
+    if (!sameFile(before, opened) || opened.size > MAX_BYTES) throw storeError()
+    // Bound the read even if an abnormal writer grows the file after fstat.
+    const bytes = Buffer.alloc(MAX_BYTES + 1)
+    let length = 0
+    while (length < bytes.length) {
+      const result = await file.read(bytes, length, bytes.length - length, length)
+      if (!result.bytesRead) break
+      length += result.bytesRead
+    }
+    if (length > MAX_BYTES) throw storeError()
+    return snapshotRecord(sessionId, JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))))
+  } finally {
+    await file.close()
+  }
+}
+
+async function acquireLock(path) {
+  const deadline = performance.now() + LOCK_TIMEOUT_MS
+  while (true) {
+    let file
+    let stat
+    try {
+      file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+      stat = await file.stat()
+      await file.chmod(0o600)
+      assertOwned(await file.stat(), 'file')
+      return { file, stat }
+    } catch (error) {
+      if (file) {
+        if (stat) await releaseLock(path, { file, stat })
+        else await file.close().catch(() => {})
+      }
+      if (error.code !== 'EEXIST') throw error
+      try {
+        assertOwned(await lstat(path), 'file')
+      } catch (inspectionError) {
+        if (inspectionError.code === 'ENOENT') continue
+        throw inspectionError
+      }
+      if (performance.now() >= deadline) throw storeError('ARCHIVE_STORE_CONFLICT')
+      // Never infer staleness or remove another process's lock.
+      await delay(20)
+    }
+  }
+}
+
+async function releaseLock(path, lock) {
+  try {
+    const current = await lstat(path)
+    if (!sameFile(current, lock.stat) || !current.isFile()) throw storeError()
+    await unlink(path)
+  } finally {
+    await lock.file.close()
+  }
+}
+
+async function syncDirectory(directory) {
+  // Windows does not expose fsync on directory handles through Node.
+  if (process.platform === 'win32') return
+  const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
+  try {
+    assertOwned(await handle.stat(), 'directory')
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Private transcript outboxes. No user directory is touched until load/save. */
+export function createFileConversationArchiveStore({ directory } = {}) {
+  if (directory !== undefined && (typeof directory !== 'string' || !directory.trim())) throw storeError()
+  const root = directory === undefined ? defaultDirectory() : resolve(directory)
+  return {
+    async load(sessionId) {
+      try {
+        const key = sessionKey(sessionId)
+        if (!await ensureDirectory(root, false)) return null
+        return await readRecord(join(root, `${key}.json`), sessionId)
+      } catch (error) {
+        throw safeError(error)
+      }
+    },
+    async save(sessionId, record, expectedRevision) {
+      let lock
+      let temporaryPath
+      const key = sessionKey(sessionId)
+      const path = join(root, `${key}.json`)
+      const lockPath = join(root, `${key}.lock`)
+      try {
+        const copy = nextRecord(sessionId, record, expectedRevision)
+        await ensureDirectory(root, true)
+        lock = await acquireLock(lockPath)
+        assertRevision(await readRecord(path, sessionId), expectedRevision)
+        temporaryPath = join(root, `.${key}.${randomUUID()}.tmp`)
+        const temporary = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+        try {
+          await temporary.chmod(0o600)
+          assertOwned(await temporary.stat(), 'file')
+          await temporary.writeFile(JSON.stringify(copy), 'utf8')
+          await temporary.sync()
+        } finally {
+          await temporary.close()
+        }
+        await rename(temporaryPath, path)
+        temporaryPath = undefined
+        await syncDirectory(root)
+        return snapshotRecord(sessionId, copy)
+      } catch (error) {
+        throw safeError(error)
+      } finally {
+        try {
+          if (temporaryPath) await unlink(temporaryPath).catch((error) => {
+            if (error.code !== 'ENOENT') throw storeError()
+          })
+        } finally {
+          if (lock) {
+            try {
+              await releaseLock(lockPath, lock)
+            } catch {
+              throw storeError()
+            }
+          }
+        }
+      }
+    },
+  }
+}
+
+/** Explicit in-memory adapter: CAS-compatible, but never survives process restart. */
+export function createMemoryConversationArchiveStore() {
+  const records = new Map()
+  return {
+    async load(sessionId) {
+      sessionKey(sessionId)
+      const record = records.get(sessionId)
+      return record ? snapshotRecord(sessionId, record) : null
+    },
+    async save(sessionId, record, expectedRevision) {
+      const copy = nextRecord(sessionId, record, expectedRevision)
+      assertRevision(records.get(sessionId), expectedRevision)
+      records.set(sessionId, copy)
+      return snapshotRecord(sessionId, copy)
+    },
+  }
+}