@sqdr2/dsh-fusion 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# Fusion · DSH 插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.en.md) · [安装](INSTALL.zh.md) · [Install (English)](INSTALL.md)
+
+> **本仓库是 [`aa2246740/dsh-model-fusion`](https://github.com/aa2246740/dsh-model-fusion) 的 fork，包名 `@sqdr2/dsh-fusion`。**
+> 上游的能力、算法和实测数据全部保留；本 fork 专注于三件事：把入口从「设置」搬到左侧边栏、
+> 让 agy 线路（[`dsh-agy-worker`](https://github.com/SQDR2/dsh-agy-worker)）真的能当 Sidekick、
+> 以及修掉冻结范围与任务记录上几个会卡住流程的问题。改动清单见 [本 fork 做了什么](#本-fork-做了什么)。
+
+Fusion 在 DeepSeek Harness（DSH）的模型菜单里是一个普通模型：**Fusion · 自动**。背后是两个你自己选的模型：
+
+- **Lead**：一个强的前沿模型。负责理解需求、看代码、写任务说明、审查结果。
+- **Sidekick**：一个便宜得多的模型。负责实际改代码、跑命令、跑测试。
+
+目标只有一个：**用前沿模型的效果，付打折的价钱。**
+
+思路受 Cognition 在 Devin 里推出的 Fusion 启发，这是一个独立实现，与 Cognition 无关。
+
+## 实测效果
+
+9 道真实开源项目的题（SWE-rebench，Python），每题跑 2 次，用隐藏测试判定对错。Lead 为 GPT-6 Astra（high），Sidekick 为 GLM-5.3-Flash（high）：
+
+| | 做对 | 总花费（按 API 价格估算） |
+|---|---|---|
+| GPT-6 Astra 单独 | 9/18 | $39.17 |
+| **Fusion：GPT-6 Astra + GLM-5.3-Flash** | **11/18** | **$18.07（便宜 54%）** |
+| Fusion：GPT-6 Astra + Grok 4.6 | 13/18 | $41.27（不省钱） |
+
+- 花费是按各家 API 公开价格换算的估算，不是账单。
+- 局限：样本小（9 题 × 2 次）、只测了 Python、公开题目可能出现在模型训练数据里。
+- 详细方法、原始数据和每一轮的结论见 [docs/EVIDENCE.md](docs/EVIDENCE.md)。
+
+**对照 Devin 自己的 Fusion：** 两边用同一对模型，Lead 是 GPT-6 Astra（high），Sidekick 是 SWE-2。题目、工作区和隐藏测试完全相同。
+
+排除被污染的尝试后，四个组别都干净的题剩 4 道，结果如下：
+
+| | 做对 | 花费 |
+|---|---|---|
+| **本插件：Astra + SWE-2** | **4/4** | **$2.73** |
+| Devin Fusion：Astra + SWE-2 | 3/4 | $4.81 |
+| Devin，Astra 单独 | 3/4 | $8.13 |
+
+- 样本只有 4 道题、每题 1 次，不能据此说谁更强，也不代表与 Devin 同等水平。
+- SWE-2 两边都按 $0 计价，所以花费都是 Lead 的。
+- 本插件的耗时约为 Devin 的 3.4 倍。
+- 排除了哪些尝试、为什么排除，以及方法和原始数据，见 [docs/EVIDENCE.md](docs/EVIDENCE.md#against-devins-own-fusion-round-devin-r1-2026-09-29)。
+
+## 怎么用
+
+1. 按 [安装说明](INSTALL.zh.md) 装好插件。
+2. 打开左侧边栏的 **Fusion** 入口（默认位于记忆系统下方），选择 Lead 和 Sidekick。可以选 DSH 里任何已登录的模型。
+3. 在模型菜单里选择 **Fusion · 自动**，像平时一样对话。
+
+**搭配建议：** 省钱靠的是 Sidekick 比 Lead 便宜得多。选一个强的前沿模型当 Lead，再选一个价格低很多（最好 5 倍以上）的模型当 Sidekick。两者价格越接近，越省不了钱。
+
+## 工作方式
+
+- **普通对话**：Lead 直接回答，和用普通模型一样。
+- **需要改代码时**：Lead 把任务交给 Sidekick。任务说明里带着用户需求的原话，以及验收命令。
+- **验收**：
+  - Sidekick 交回结果后，DSH 在真实环境里运行验收命令。
+  - Lead 审查改动，并且必须对用户的每一条硬性要求给出结论和证据，缺一条都不能通过。
+  - 原本就失败的测试（例如缺少可选依赖），可以标成"只要求不新增失败"。
+  - Sidekick 改写了原有测试时，会被单独标出来，Lead 必须确认过才能通过。
+- **返工**：不通过就把具体问题打回给同一个 Sidekick 继续改。
+  - 如果发现任务说明里允许改的文件不够（例如另一个测试文件还写着旧行为），Lead 可以在返工时把它加进可改范围。只能加、不能减，每次都会留下记录。
+- **Lead 不写代码**：这不是靠提示词约束，而是由程序保证的：
+  - Lead 没有写文件的工具；
+  - 它执行的 shell 命令跑在 DSH 的只读沙盒里。
+- **唯一的例外：程序判定 Sidekick 确实做不完时，才解锁 Lead 接手。** 例如 2 轮返工后检查仍然失败，或者 Sidekick 用完了步数、反复卡住。接手时：
+  - Lead 只能改任务允许的文件；
+  - 必须通过同样的验收；
+  - 任务结束后恢复只读。
+- **额度用完或出错**：Lead、Sidekick 各自处理。可以换模型继续，也可以定时继续；进度保留。
+
+## 用 agy 当 Sidekick（dsh-agy-worker）
+
+[`dsh-agy-worker`](https://github.com/SQDR2/dsh-agy-worker)（`dsh-agy-link` 的 fork）把 Google Antigravity 的模型接进 DSH，可以当 Sidekick 用。这条路和普通模型线路不一样，**必须三个条件同时成立**，缺任何一条都会静默失败：
+
+| 条件 | 为什么 | 缺了会怎样 |
+|---|---|---|
+| `mcpBridge: true` | agy 要能真的**执行** DSH 工具 | 工具看得见，但调不动 |
+| `permissionMode: 'skip'` | headless 下 MCP 调用要被自动允许 | agy 直接拒绝：`a tool required the "mcp" permission that headless mode cannot prompt for` |
+| 白名单里有 `fusion_*` | Sidekick 要能**交回结果** | 只能诊断，永远交不回 |
+
+工具天花板里的回传通道 `agy_tool` **不需要你手写**：本插件在检测到 `antigravity` 线路已注册时，会自动把它并进 Lead 和 Sidekick 的工具面（`src/host/route-transport.ts`）。这是本 fork 修掉的问题之一——在此之前，agy 的适配器只能以 `agy_tool` 回传，而天花板里没有这个名字，整轮就退化成纯文本，宿主报 `WORKER_TOOLS_UNREACHABLE`。
+
+推荐配置：
+
+```yaml
+- id: dsh-agy-worker
+  config:
+    mcpBridge: true
+    permissionMode: skip
+    mcpConfigScope: global
+    mcpToolAllowlist: "fusion_submit_result,fusion_read_state,fusion_read_evidence,bash,read,write,edit,glob,grep,job_output,job_kill"
+```
+
+> Windows 把 `bash` 换成 `pwsh`；改过 `workerTools` 就跟着改。完整配置面、验证步骤与排障对照见
+> [dsh-agy-worker 的 MCP 桥接文档](https://github.com/SQDR2/dsh-agy-worker/blob/main/docs/MCP-BRIDGE-SETUP.md)。
+
+## 本 fork 做了什么
+
+相对上游 `dsh-model-fusion`，本 fork 的改动（按提交时间）：
+
+| 内容 | 解决了什么 |
+|---|---|
+| **用户约束跨压缩保留** | 对话被自动压缩（rollover）后，用户原话里的硬性要求仍在任务范围内，不会因为一次压缩就丢掉验收依据 |
+| **死路任务有出口** | 当 Sidekick 线路根本够不到工具时，判定会被记在运行记录上：`fusion_wait` 复述同一个原因，`fusion_delegate` 允许替换这条死单并复用常驻身份，不再把任务卡在 `WORKER_RUNNING` |
+| **入口搬到左侧边栏** | Fusion 从「设置 → Fusion」变成左侧边栏的独立面板（默认落在记忆系统下方），主区域有真正的滚动面，不再是塞在设置页里的一段表单 |
+| **agy 线路真的能当 Sidekick** | `agy_tool` 回传通道自动并进工具天花板（见上一节） |
+| **桥接线路能交回结果** | agy 在自己的循环里执行调用，用的是 `agy-mcp-N` 这种桥内 id，本 Host 的 assistant 消息里没有它，于是所有非只读 Worker 工具都被判成「缺少完整的原生模型请求」——包括唯一要紧的 `fusion_submit_result`。现在桥接调用归属到发出回传通道的那条消息上，原生路径不变且优先 |
+| **冻结范围不再死锁** | `allowedPaths: ['lib/types/**']` 这类 glob 之前一条都不匹配，导致「改动落在冻结范围外」和「加范围时文件已变更」互相锁死。现在 glob 正常匹配，加范围改为按提交基点比较，并且可以显式清空 |
+| **任务记录可以删了** | 删除只看持久化状态：进程换过的任务永远 `running` 删不掉，而真在跑的 Agent 又可能被从底下抽走。现在删除先问协调者（`liveWork`），409 会说明是哪一个资源占着 |
+| **面板折叠** | 用量统计、任务列表、缓存保活、历史各自成为独立的折叠区块，默认收起，模型组合不再被挤到屏幕外 |
+
+## 缓存保活
+
+Lead 等 Sidekick 干活时，可能要等好几分钟。模型的输入缓存过期后，下一次请求就要按全价重读整段对话。保活会在等待期间，定时把 Lead 上一次的请求原样再发一遍，末尾只加一句“Reply OK”。前缀和上次完全相同，厂商就从缓存读取，缓存的寿命也就续上了；模型只回一个 OK，回复直接丢弃，不进对话，也不会执行工具调用。
+
+- **默认值：** 来自各家官方文档，覆盖 Artificial Analysis 排行榜前 20 的模型厂商。
+  - 按模型名匹配，比如 gpt-*、claude-*、gemini-*、glm-*、grok-*、kimi-*、deepseek-*。
+  - 附带 [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login) 的线路计费方式：按请求次数计费的套餐默认关闭保活，因为每次保活都算一次请求。
+- **自动：** 模型实际返回过缓存命中后才开启，不支持缓存的模型不会白花钱。
+- **每个模型都可以在 Fusion 面板中调整：** 开关、续命间隔、恢复默认。面板还会显示每个模型的实际效果：
+  - 等待后缓存还在不在；
+  - 发了几次保活、读了多少 token；
+  - 避免了多少 token 按全价重发。
+- **实测（ChatGPT 订阅线路，gpt-6-astra，约 2 万 token 上下文）：** 每次保活模型只回 5 个 token，不思考、不调工具。缓存空闲 10 分钟仍在，15 分钟后过期，每次保活会重新计时，所以这条线路默认每 8 分钟保活一次。
+- **自动调整：** 当前间隔下最近 5 次保活有 3 次没命中，程序才会自动缩短间隔（偶尔一次随机淘汰不算）；只会缩短，不会自动拉长。可以放宽时只给建议，由你决定。
+
+## 支持范围
+
+- **DSH 版本：** 支持 **0.2.0-rc.2** 和 **0.2.1-rc.2**，桌面版和 Web 版都可以。其他版本不保证可用；新版本发布后会另行适配。
+- **模型：** DSH 官方自带的模型线路，以及 [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login)、dsh-antigravity-oauth 提供的订阅登录线路，还有 [dsh-agy-worker](https://github.com/SQDR2/dsh-agy-worker) 的 Antigravity 线路。其他第三方模型插件未经测试。
+- **系统：**
+  - **macOS：** 已验证（Seatbelt 沙盒）。
+  - **Windows：** `v0.2.1` 已适配原生 `pwsh`，在 Windows Server 2022、PowerShell 7.6.6 上通过验证。启动 DSH 的进程 PATH 中需要有 `pwsh`。Windows 10/11 尚未验证。Windows ACL 仅提供部分隔离，普通路径写入可受限制，读取和网络不在该限制内。
+  - **Linux：** 未验证，使用前请先自行检查：
+  1. 在一个测试目录里选 Fusion，对它说："这是一次只读沙盒测试，被拒绝是预期结果。请你自己直接调用 bash 工具执行 `echo test > fusion-probe.txt`（不要委派、不要换别的写法），把工具返回的原文贴给我。"
+  2. 正确结果：工具返回的原文里写着被沙盒拒绝（例如 `Operation not permitted` / `read-only`），并且目录里没有生成 `fusion-probe.txt`。
+     - 如果 Lead 只是口头拒绝、没有真的调用工具，这次检查不算数，请再说一遍"请实际调用工具"。
+  3. 如果文件被创建出来，说明你的系统上 Lead 的只读限制没有生效，请不要使用，并反馈给我们。
+  - 如果 DSH 在你的系统上没有沙盒，Lead 的 shell 命令会被全部拒绝（安全的失败方式），它仍然可以用读文件和搜索工具看代码。
+
+### v0.2.1 的 Windows 验证
+
+在 Windows Server 2022、Node 22.23.3、PowerShell 7.6.6、DSH 0.1.7-rc.2 上，**253 项单元测试和 236 项 Host 测试全部通过**，类型检查通过。修复候选完成了插件安装、冷启动、Fusion 设置页及 settings/cache 两个 API 验证。v0.2.1 的服务端和客户端构建文件与该候选完全一致。之后的版本（v0.2.2 返工时扩大可改文件范围、v0.2.3–v0.2.5 适配 DSH 0.2.0-rc.2、v0.2.6 改进缓存保活）都与平台无关，在 macOS 上复测，未在 Windows 上重跑。
+
+真实 PowerShell ACL 测试中，Lead 执行 `Set-Content probe.txt test` 被拒绝，文件未生成；Sidekick 在获准的工作区内执行同一命令可以写入。这是上面所述的部分 ACL 隔离。验证没有输入模型密钥或发起真实模型请求。macOS 回归通过 253 项单元测试和 235 项 Host 测试，按设计跳过 Windows 专用 ACL 测试。
+
+## 数据存在哪里
+
+- **Fusion 自己的记录：** 任务说明、检查结果、用量、缓存统计和设置，都存在 `$DSH_HOME/plugins/dsh-fusion/state.sqlite`。`DSH_HOME` 默认是 `~/.dsh`。
+- **从旧名字升级：** 上一版叫 `dsh-model-fusion`，它的整个数据目录（`$DSH_HOME/plugins/dsh-model-fusion/`）会在首次启动时**整体迁移**到新名字，已有的任务、用量和设置都还在。跨文件系统时会退化成复制数据库和它的 `-wal`/`-shm`/`-journal`，只删除自己复制过的文件。
+- **会话本身：** 由 DSH 保存，Fusion 不另外上传任何数据。
+- **想清空 Fusion 的记录：** 退出 DSH 后删除这个文件。设置也会一起清掉，下次打开时重新选组合即可。
+
+## 已知限制
+
+- **比单独用前沿模型慢：** 实测 GPT-6 + Flash 总耗时约为 GPT-6 单独的 5 倍，主要花在 Sidekick 身上。换更快的 Sidekick 会好很多。
+- **Lead 接手：** 在 72 次实测里一次都没触发，目前只由自动化测试覆盖。
+- **macOS 桌面版的 PATH：** 从程序坞打开的 DSH Studio 只有系统默认的 PATH，Homebrew（`/opt/homebrew/bin`）、nvm 等装的 `node`、`npm`、`cargo` 在 shell 里找不到。这是 DSH 的运行环境，所有模型都一样。Fusion 在派活前会检查验收命令用到的程序，找不到时会告诉 Lead 它实际装在哪里（例如 `/opt/homebrew/bin/node`），Lead 改用完整路径即可。
+- **Windows 10/11 和 Linux 未验证：** 见上面的"系统"。
+
+## 开发
+
+```sh
+corepack pnpm@9.15.9 install --frozen-lockfile
+node scripts/link-host.mjs /path/to/deepseek-harness-0.2.0-rc.2   # 或 0.2.1-rc.2；开发时链接 DSH 源码
+DSHX_HARNESS=/path/to/deepseek-harness-0.2.0-rc.2 pnpm build
+pnpm test && DSHX_HARNESS=/path/to/deepseek-harness-0.2.0-rc.2 pnpm test:host
+```
+
+Windows 开发环境需将 PowerShell 7（`pwsh`）、Node 和 Python 加入运行测试的进程 PATH。原生测试通过 `DSHX_HARNESS` 读取已构建的指定 Host；不需要修改 Host 源码。
+
+插件只使用 DSH 公开的插件接口，不修改 DSH 源码。适配新版本 DSH 的做法见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。
+
+## 许可
+
+Apache-2.0。上游 fork 自 [`aa2246740/dsh-model-fusion`](https://github.com/aa2246740/dsh-model-fusion)，同样以 Apache-2.0 发布。

package/contracts/fusion.ts

@@ -0,0 +1,279 @@
+/**
+ * Proposed plugin-domain contracts, NOT existing DSH API declarations.
+ * No runtime behavior or authorization is supplied by these types.
+ * Convert DSH branded IDs only in the version-pinned bridge layer.
+ */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+export type TaskId = Brand<string, 'FusionTaskId'>;
+export type SessionId = Brand<string, 'DshSessionId'>;
+export type WorkOrderId = Brand<string, 'FusionWorkOrderId'>;
+export type OperationId = Brand<string, 'FusionOperationId'>;
+export type ArtifactId = Brand<string, 'FusionArtifactId'>;
+export type SnapshotId = Brand<string, 'FusionSnapshotId'>;
+export type Digest = Brand<string, 'Sha256Hex'>;
+/** Decimal string avoids binary-float money and is JSON serializable. */
+export type UsdDecimal = Brand<string, 'UsdDecimal'>;
+export type EpochId = Brand<string, 'ContextEpochId'>;
+
+export interface PhysicalRoute {
+  provider: string;
+  model: string;
+  reasoningEffort?: string; // Validate against the owning adapter's opaque IDs.
+}
+export type RunSelection =
+  | { kind: 'model'; route: PhysicalRoute }
+  | { kind: 'profile'; profileId: string; requestedVersion?: string };
+export type Role = 'lead' | 'worker';
+export type Phase =
+  | 'READY' | 'PLANNING' | 'DIRECT' | 'WORKER_RUNNING' | 'REVIEWING'
+  | 'REWORK' | 'WAITING_APPROVAL' | 'WAITING_USER' | 'WAITING_BUDGET'
+  | 'RECOVERING' | 'PAUSED' | 'STOPPING' | 'NEEDS_DECISION'
+  | 'FAILED' | 'COMPLETED' | 'CANCELLED';
+export type VerificationLevel = 'unverified' | 'partial' | 'verified';
+
+export interface SourceRef {
+  sessionId: SessionId;
+  eventSeq: number;
+  messageId?: string;
+}
+export interface ArtifactRef {
+  id: ArtifactId;
+  digest: Digest;
+  ownerTaskId: TaskId;
+  mediaType: string;
+  bytes: number;
+}
+export interface Constraint {
+  id: string;
+  text: string;
+  source: SourceRef;
+  provenance: 'user' | 'policy' | 'inferred';
+  mandatory: boolean;
+}
+export interface AcceptanceCriterion {
+  id: string;
+  description: string;
+  verificationKind: 'test' | 'static-check' | 'human' | 'review';
+  mandatory: boolean;
+  verifierId?: string;
+  planId?: string;
+  planDigest?: Digest;
+}
+export interface ResourcePolicy {
+  maxWorkerSteps: number;
+  maxReworkRounds: number;
+  maxCapabilityUpgrades: number;
+  modelSpendAuthorizationId?: string;
+  maxApiCostUsd?: UsdDecimal;
+  maxTotalOutputTokens: number;
+  /** Human approval has no expiry; only machine execution has a deadline. */
+  commandMaxSeconds: number;
+}
+export interface WorkOrder {
+  schemaVersion: 1;
+  taskId: TaskId;
+  id: WorkOrderId;
+  operationId: OperationId;
+  revision: number;
+  goal: string;
+  constraints: readonly Constraint[];
+  acceptance: readonly AcceptanceCriterion[];
+  allowedPaths: readonly string[];
+  forbiddenActions: readonly string[];
+  baseSnapshot: SnapshotId;
+  evidence: readonly ArtifactRef[];
+  decisions: readonly { text: string; source: SourceRef }[];
+  uncertainties: readonly string[];
+  policy: ResourcePolicy;
+}
+export interface CoverageClaim {
+  criterionId: string;
+  state: 'satisfied' | 'not-satisfied' | 'not-verified';
+  evidenceIds: readonly ArtifactId[];
+  explanation: string;
+}
+export interface WorkerReport {
+  schemaVersion: 1;
+  workOrderId: WorkOrderId;
+  revision: number;
+  status: 'completed' | 'blocked' | 'needs-decision';
+  summary: string;
+  snapshot: SnapshotId;
+  changeManifest: ArtifactRef;
+  coverage: readonly CoverageClaim[];
+  verification: readonly ArtifactRef[];
+  unresolved: readonly string[];
+  questions: readonly string[];
+}
+export interface ToolEvidence {
+  schemaVersion: 1;
+  taskId: TaskId;
+  operationId: OperationId;
+  actor: SessionId;
+  nativeToolCallId: string;
+  argvDigest: Digest;
+  cwdDigest: Digest;
+  inputSnapshot: SnapshotId;
+  outputSnapshot?: SnapshotId;
+  exitCode: number | null;
+  startedAt: string;
+  endedAt: string | null;
+  stdout: ArtifactRef;
+  stderr: ArtifactRef;
+  state: 'started' | 'completed' | 'cancelled' | 'outcome-unknown';
+  kind?: 'tool' | 'human-decision' | 'review-accept';
+}
+export interface ContextCheckpoint {
+  schemaVersion: 1;
+  epochId: EpochId;
+  taskId: TaskId;
+  revision: number;
+  goal: string;
+  mandatoryConstraints: readonly Constraint[];
+  snapshot: SnapshotId;
+  decisions: readonly { text: string; source: SourceRef }[];
+  coverage: readonly CoverageClaim[];
+  pendingApprovalIds: readonly string[];
+  openQuestions: readonly string[];
+  evidence: readonly ArtifactRef[];
+  sourceSurfaceSeqs: readonly number[]; // Surface order, NOT numeric sorting.
+  digest: Digest;
+}
+export interface RoleContextPolicy {
+  targetInputTokens: number;
+  reserveOutputTokens: number;
+  minSafetyTokens: number;
+  safetyFraction: number;
+  compactToFraction: number;
+  evidenceReadTokens: number;
+  maxToolVisibleTokens: number;
+}
+export interface PairProfile {
+  schemaVersion: 1;
+  id: string;
+  version: string;
+  digest: Digest;
+  enabled: boolean;
+  quality: 'experimental' | 'validated' | 'deprecated';
+  lead: PhysicalRoute;
+  worker: PhysicalRoute;
+  workerUpgradePath: readonly PhysicalRoute[];
+  promptDigests: Readonly<Record<'lead' | 'worker' | 'compact', Digest>>;
+  context: Readonly<Record<Role, RoleContextPolicy>>;
+  /** Experimental auxiliary calls, explicitly enabled for the frozen routes. */
+  cacheKeepalive?: Readonly<Record<Role, boolean>>;
+  /** Optional explicit summary route. Missing means the current role model. */
+  compactor?: { readonly route: PhysicalRoute; readonly maxOutputTokens: number };
+  dataPolicyId: string;
+  evidenceCampaignIds: readonly string[];
+}
+export interface LogicalApproval {
+  id: string;
+  taskId: TaskId;
+  revision: number;
+  operationId: OperationId;
+  nativeRequestId?: string;
+  argsDigest: Digest;
+  snapshot: SnapshotId;
+  permissionPolicyDigest: Digest;
+  state: 'pending' | 'approved' | 'rejected' | 'withdrawn' | 'consumed';
+  decisionBy?: 'human' | 'preauthorized-policy';
+  /** No expiresAt: pending human work does not expire automatically. */
+}
+export interface WriteLease {
+  workspaceId: string;
+  holder: SessionId;
+  taskId: TaskId;
+  generation: number;
+  activeOperationIds: readonly OperationId[];
+}
+export interface TokenMeasurement {
+  inputTokens: number;
+  reservedOutputTokens: number;
+  contextWindow: number;
+  safetyTokens: number;
+  quality: 'exact' | 'provider-estimated' | 'heuristic';
+  requestDigest: Digest;
+}
+/** Mutually exclusive buckets. Null means unavailable, never zero. */
+export type UsageApplicability = 'not_applicable' | 'unknown' | 'known';
+export interface NormalizedUsage {
+  uncachedInput: number | null;
+  cacheRead: number | null;
+  cacheReadStatus: UsageApplicability;
+  cacheWrite: Readonly<Record<string, number | null>>;
+  cacheWriteStatus: Readonly<Record<string, UsageApplicability>>;
+  output: number | null;
+  /** Informational subset; do not charge again if included in output. */
+  reasoningOutputSubset: number | null;
+  /** Separately billed reasoning. Charge at the reasoning or output rate. */
+  reasoningSeparate: number | null;
+  /** Reasoning tokens whose include-in-output contract is unknown. */
+  reasoningUnspecified: number | null;
+  reasoningBilling: {
+    kind: 'included' | 'separate' | 'unknown' | 'not_applicable';
+    tokens: number | null;
+  };
+  inputIncludesCacheRead: boolean | null;
+}
+
+export interface ReportSubject {
+  taskId: TaskId;
+  workOrderId: WorkOrderId;
+  revision: number;
+  reportId: string;
+  reportDigest: Digest;
+  snapshot: SnapshotId;
+}
+export interface ReviewTicket {
+  id: string;
+  requestId: string;
+  generation: number;
+  subject: ReportSubject;
+  validationDigest: Digest;
+  workOrderDigest: Digest;
+}
+export interface ControlState {
+  mode: 'running' | 'paused' | 'stop-requested' | 'cancelled' | 'completed';
+  pendingApprovalIds: readonly string[];
+  budgetBlocked: boolean;
+  recovering: boolean;
+  outcomeUnknown: boolean;
+}
+export interface UsageAttempt {
+  attemptId: string;
+  taskId: TaskId;
+  agentId: SessionId;
+  role: Role;
+  purpose: 'conversation' | 'compaction' | 'review' | 'routing' | 'other';
+  route: PhysicalRoute;
+  epochId: EpochId;
+  serviceTier?: string;
+  rawUsage?: ArtifactRef;
+  normalized: NormalizedUsage;
+  priceCardDigest?: Digest;
+  apiEquivalentUsd: UsdDecimal | null;
+  actualBilledUsd: UsdDecimal | null;
+  status: 'pending' | 'complete' | 'partial' | 'unknown';
+}
+export interface EventEnvelope<T extends string, P> {
+  schemaVersion: 1;
+  id: string;
+  taskId: TaskId;
+  seq: number;
+  revision: number;
+  type: T;
+  createdAt: string;
+  causeId: string;
+  payload: P;
+}
+export type FusionEvent =
+  | EventEnvelope<'task/created', { parent: SessionId; selection: RunSelection }>
+  | EventEnvelope<'work-order/prepared', { order: WorkOrder; reservedChild: SessionId }>
+  | EventEnvelope<'child/accepted', { operationId: OperationId; child: SessionId; messageId: string }>
+  | EventEnvelope<'report/validated', { operationId: OperationId; report: WorkerReport }>
+  | EventEnvelope<'approval/pending', { approval: LogicalApproval }>
+  | EventEnvelope<'effect/outcome-unknown', { operationId: OperationId; reason: string }>
+  | EventEnvelope<'task/completed', { snapshot: SnapshotId; verification: VerificationLevel }>
+  | EventEnvelope<'task/paused', { reason: string }>;
+// Expand this union when implementing all specified event kinds; do not use any.

package/contracts/storage.sql

@@ -0,0 +1,86 @@
+-- Optional SQLite task store. Does not replace or share a transaction with DSH Session.
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+CREATE TABLE IF NOT EXISTS schema_meta(version INTEGER NOT NULL);
+INSERT INTO schema_meta(version) SELECT 1 WHERE NOT EXISTS (SELECT 1 FROM schema_meta);
+CREATE TABLE IF NOT EXISTS tasks (
+ task_id TEXT PRIMARY KEY,
+ revision INTEGER NOT NULL CHECK(revision >= 1),
+ state TEXT NOT NULL,
+ parent_session_id TEXT NOT NULL,
+ profile_digest TEXT NOT NULL,
+ state_seq INTEGER NOT NULL DEFAULT 0 CHECK(state_seq >= 0),
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS events (
+ event_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ seq INTEGER NOT NULL CHECK(seq >= 1),
+ revision INTEGER NOT NULL CHECK(revision >= 1),
+ type TEXT NOT NULL,
+ payload_version INTEGER NOT NULL,
+ payload_json TEXT NOT NULL,
+ cause_id TEXT NOT NULL,
+ created_at TEXT NOT NULL,
+ UNIQUE(task_id,seq)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+ artifact_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ content_digest TEXT NOT NULL,
+ storage_ref TEXT NOT NULL,
+ bytes INTEGER NOT NULL CHECK(bytes >= 0),
+ media_type TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS work_orders (
+ work_order_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ revision INTEGER NOT NULL,
+ child_session_id TEXT NOT NULL,
+ status TEXT NOT NULL,
+ brief_artifact_id TEXT NOT NULL REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS outbox (
+ operation_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ kind TEXT NOT NULL,
+ state TEXT NOT NULL,
+ payload_artifact_id TEXT NOT NULL REFERENCES artifacts(artifact_id),
+ native_message_id TEXT,
+ result_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS effects (
+ effect_id TEXT PRIMARY KEY,
+ operation_id TEXT NOT NULL UNIQUE REFERENCES outbox(operation_id),
+ args_digest TEXT NOT NULL,
+ snapshot_id TEXT NOT NULL,
+ stage TEXT NOT NULL,
+ outcome_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS logical_approvals (
+ logical_id TEXT PRIMARY KEY,
+ effect_id TEXT NOT NULL UNIQUE REFERENCES effects(effect_id),
+ decision TEXT NOT NULL CHECK(decision IN ('pending','approved','rejected','withdrawn','consumed')),
+ native_request_id TEXT,
+ decision_scope_digest TEXT NOT NULL,
+ updated_at TEXT NOT NULL
+ -- Intentionally no expiry column for pending human decisions.
+);
+CREATE TABLE IF NOT EXISTS usage_attempts (
+ attempt_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ accounting_status TEXT NOT NULL,
+ normalized_json TEXT NOT NULL,
+ raw_usage_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS leases (
+ workspace_id TEXT PRIMARY KEY,
+ generation INTEGER NOT NULL CHECK(generation >= 1),
+ owner_task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ live_process_refs_json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS events_by_task ON events(task_id,seq);
+CREATE INDEX IF NOT EXISTS outbox_pending ON outbox(state,task_id);
+-- Application must perform state/version CAS + event append + outbox write in one transaction.
+-- SQL uniqueness is not proof of exactly-once external side effects.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-fusion
+      name: '@sqdr2/dsh-fusion'