@orion-agents/orion-code 0.2.2 → 0.3.1

package/docs/migration/v0.2.2-to-v0.3.0-settings.md

@@ -0,0 +1,114 @@
+# Orion Code v0.2.2 → v0.3.0 Settings 迁移说明
+
+v0.3.0 将 Web 端设置升级为 Host 管理的持久 Settings 子系统。迁移不会引入
+`settings.json`；`$ORION_CODE_CONFIG_DIR/orion.json` 仍然是唯一配置真源。
+
+## 迁移前准备
+
+1. 备份现有 `orion.json`。
+2. 确认文件是有效 JSON，且当前 Orion Code 可以正常启动。
+3. 不要将 API key、Authorization Header 或其他凭证粘贴到浏览器问题报告中。
+
+v0.3.0 的 Settings 页只显示 Provider 的 `ready`/`missing`/`unavailable` 状态，不会返回
+凭证值、环境变量名、Header 或配置文件路径。
+
+## 主题与动效
+
+旧 Web 页面把主题和动效保存在浏览器 `localStorage`。v0.3.0 将它们保存到：
+
+```json
+{
+  "web": {
+    "appearance": {
+      "theme": "system",
+      "motion": "system"
+    }
+  }
+}
+```
+
+首次打开 v0.3.0 Web Workbench 时：
+
+- Host 已有显式值：Host 值优先，清理旧浏览器值。
+- Host 没有显式值且浏览器有旧值：通过一次 revision CAS 导入；只在 Host
+  确认持久化后删除旧值。
+- 多标签页同时导入：只有一个 CAS 成功，其他页面重读 Host，不覆盖已保存值。
+
+“重置为继承值”会删除对应字段，不会把当前 effective value 反写为新的显式值。
+
+## 默认模型与当前会话模型
+
+Settings 中的“默认模型”写入根级 `defaultModel`，仅影响之后创建的 Session。
+
+- 已打开 Session 不会被 Settings 暗中切换模型。
+- `/model <id>` 仍然是当前 Session 控制，并持久到该 Session metadata。
+- 修改 `/model` 不会更改全局 `defaultModel`。
+
+页面会同时显示默认模型和当前 Session 模型，以避免两种作用域混淆。
+
+## Effort 作用域
+
+Settings 中的 Effort 是当前 workspace 的 project default，保存到：
+
+```text
+projects[canonical active workspace].defaultEffort
+```
+
+有效值的统一解析顺序为：
+
+```text
+Session override → project default → global default → model capability default
+```
+
+Session 已有显式 Effort 时，修改 project default 不会覆盖它。无 Session override 时，
+新值从下一个逻辑请求开始生效。
+
+## 工具确认策略
+
+Settings 中的 `ask`/`allow`/`deny` 是全局 `toolConfirmation` 默认策略。该设置只在
+Runtime idle 边界提交，从下一个逻辑请求开始生效。
+
+`allow` 不会绕过工具硬拒绝、allowlist、sandbox、workspace 边界或风险上限。
+
+## 并发编辑与无效配置
+
+Settings 使用不透明的持久 revision 和文件锁内 CAS：
+
+- 多个标签页或外部编辑同时修改时，旧 revision 会收到冲突；未提交草稿保留。
+- 一次“应用”只发送一个 batch，全部成功或零字段提交。
+- 外部写入非法 JSON 或非法 schema 时，Runtime 保留 last-good 配置，Web 写入被禁用。
+- 修复 `orion.json` 后刷新 Settings，再基于最新 revision 保存。
+
+Advanced 页的“打开配置文件”是无 path 的受控操作：浏览器不能指定任意路径，
+响应也不会返回本地绝对路径。
+
+## 回滚
+
+需要回到 v0.2.2 时：
+
+1. 停止 Orion Code Host。
+2. 用迁移前备份恢复 `orion.json`。v0.2.2 会忽略未识别的 `web` 字段，但恢复备份
+   可确保与升级前完全一致。
+3. 不要把 revision key 当作配置文件；它仅用于本机 CAS revision，不包含设置值。
+
+回滚不需要将主题/动效重新写回浏览器。
+
+## 迁移验证记录
+
+2026-08-27 的 v0.3.0 确定性验证已直接覆盖上述迁移边界：
+
+- `SET-P0-01` 验证 legacy localStorage appearance 只导入一次，并在刷新、
+  换端口和 Host 重启后保留；
+- `SET-P0-02/03` 验证默认模型/当前 Session 及 project/global/session Effort 的
+  作用域与重启解析；
+- `SET-P0-06..10` 验证多标签 CAS、外部合法/非法编辑、幂等重试与
+  同端口 Host 重启换 nonce；
+- 同一冻结的 `@orion-agents/orion-code@0.3.0` tgz 已在 Node 20.19.5、22.22.3 和
+  24.14.1 各运行 14 个 Settings 场景，全部通过；精确候选哈希在包生成后写入不参与
+  npm 打包的资格报告，避免本迁移文档对其所在 tarball 的哈希形成循环引用。
+
+以上 Node 20/22/24 数据是历史迁移验证。当前 v0.3 Runtime 合同为 Node 22.12+/24/26；
+Node 20 已退役，历史 receipt 不能替代当前 Node 26 的 fresh exact-tarball 证据。
+
+详细 receipt、失败—修复记录与发布边界见
+[`v0.3.0 Web E2E Qualification Report`](../test/v0.3.0-web-e2e-report.md)。

package/docs/migration/v0.2.2-to-v0.3.0.md

@@ -0,0 +1,55 @@
+# Orion Code v0.2.2 → v0.3.0 Migration Guide
+
+v0.3.0 adds a local Web Workbench without replacing the existing TUI, terminal or print surfaces.
+Existing sessions, project configuration, Skill roots, MCP configuration and durable Thread logs
+remain the data sources used by both interfaces; no destructive session migration is required.
+
+## Runtime requirements
+
+- Upgrade to Node.js `22.12+`, a supported Node 24 release, or Node 26 before installing v0.3.
+  Node 20 is upstream EOL and the native dependency line no longer ships a Node 20 prebuild;
+  Node 24 LTS or Node 26 Current is recommended.
+- Run `npm install` and `npm run build`; the build now produces both `dist/` server files and
+  `dist/web-client/` browser assets.
+- Existing `orion`, `orion --ui terminal` and print-mode commands keep their current behavior.
+
+## Start the Web Workbench
+
+```bash
+orion web
+orion web --no-open --port 3080
+orion web --cwd /absolute/path/to/project
+```
+
+The host listens only on `127.0.0.1`. Static assets and `/api/v1/*` share one origin; v0.3.0 has no
+LAN/public bind option. Model/provider credentials stay in Orion configuration or environment
+variables and cannot be entered through the browser.
+
+## Behavior to note
+
+- Web, TUI and terminal use the same product composition and durable Session/Thread sources. Do not
+  run them concurrently against one active session and assume multi-writer ownership.
+- Browser refresh, SSE reconnect and tab closure do not approve or reject a pending tool request.
+  Explicit denial, runtime abort and host shutdown fail the affected request closed.
+- Approval scopes are now consistently `once`, `project` and `global`; the stale durable-protocol
+  spelling `session` is rejected.
+- Plan mode still commits a three-field Plan receipt and then schedules implementation in a new
+  logical turn. The Web UI does not add a separate Plan approval or synthetic step state.
+- Goal state shown in the browser comes from the latest valid TurnCommit. A legacy sidecar remains
+  migration input only when no committed Goal state exists.
+- Tool-output details are project scoped in v0.3.0 because current artifact metadata does not carry
+  a provable Session identity.
+- Web appearance, default model, project Effort and tool-confirmation defaults now use the
+  Host-owned, revisioned Settings coordinator. See the dedicated
+  [Settings migration guide](v0.2.2-to-v0.3.0-settings.md) before changing precedence, importing
+  legacy browser appearance or rolling configuration back.
+
+## Rollback
+
+Stop `orion web` and reinstall or run v0.2.2. v0.3.0 does not rewrite old sessions solely to enable
+the browser. New durable Thread facts remain append-only and follow the existing v0.2 recovery
+contract; back up `~/.orion-code` before any broader manual rollback or cleanup.
+
+See the [v0.3.0 Web Workbench plan](../plan/v0.3.0-web-workbench-plan.md) and
+[Settings integration plan](../plan/v0.3.0-settings-integration-plan.md), plus the
+[OpenAPI contract](../architecture/v0.3.0-web-api.yaml), for the complete boundary.

package/docs/migration/v0.3.0-to-v0.3.1.md

@@ -0,0 +1,88 @@
+# Orion Code v0.3.0 → v0.3.1 Web Workbench 迁移说明
+
+v0.3.1 将 Web Workbench 从固定三栏升级为多项目导航和专业工程面板，同时保持单一 active
+Workspace/Runtime。迁移不会复制 Session、重写 Thread history，也不会把 terminal 变成 durable Session。
+
+## 升级前准备
+
+1. 停止正在运行的 `orion web` Host，并确认重要终端任务已经结束；浏览器终端不会跨 Host 重启恢复。
+2. 备份 `$ORION_CODE_CONFIG_DIR/orion.json` 与现有 Session/Thread 数据目录。
+3. 记录当前活动 Workspace 和 Session；不要在问题报告中粘贴绝对路径、凭据或 terminal 输出。
+4. 使用受支持的 Node 22.12+、24 或 26。Node 20 不属于 v0.3.1 发布合同。
+
+## 多项目注册表
+
+首次运行时，Host 会从当前工作区和已有 Session project metadata 幂等导入 WorkspaceRegistryV1。
+
+- 注册表只保存规范化项目身份、显示标签、最近使用时间和 pin 顺序；
+- 它不会复制项目文件、删除 Session 或同时启动多个 Agent Runtime；
+- 不存在或不可访问的项目显示 unavailable，可从注册表移除；移除不删除磁盘目录或历史；
+- 展开 inactive project 只读取轻量 Session page/Git summary，不激活 Runtime；
+- 点击另一个项目的 Session 通过一次 `workspaceId + sessionId + expectedContextRevision` 原子切换。
+
+陈旧 Context guard 返回 `409 context_revision_conflict`，Host 保持原 context，且不得投递命令、
+创建 PTY、读错 workspace 或产生其他副作用。客户端应重新读取 bootstrap 后显式重试。
+
+## 布局偏好
+
+右侧 Work panel 的桌面宽度默认 420px，可用 IDE 式鼠标指针在 320–720px 间拖动调整，双击
+分隔条复位。
+
+- 精细调宽没有键盘入口；键盘用户可以展开/折叠面板，并在 drawer 中访问全部功能；
+- 窄屏自动切换 drawer，不覆盖桌面宽度偏好；返回桌面时恢复；
+- 无效或越界旧值会被 clamp/忽略，不阻止 Workbench 启动；
+- 当前面板、折叠态和桌面宽度是 UI preference，不是 Runtime 或 Session 权威状态。
+
+## 文件、Git 与审阅
+
+这些面板都是 Host 管理的只读投影：
+
+- 文件操作使用 opaque id；Host 每次读取都重新检查 canonical workspace containment；
+- sensitive file、workspace 外 symlink、non-regular path 和 stale revision 均 fail-closed；
+- Git 只使用 argv 执行 bounded status/log/diff，不提供 checkout、reset、stage、commit 或 push；
+- binary 文件只返回 metadata，文本和 Diff 采用 revision-bound 分页并在 Host 端脱敏；
+- “发送到 Composer”只把用户选择的安全文本加入草稿，不直接修改文件。
+
+## 真实终端
+
+v0.3.1 terminal 是显式用户启动的真实本地 PTY，是高权限、非 durable 表面：
+
+- 仅在 active workspace 启动，环境变量经过 allowlist/scrub；
+- attach ticket 单次使用且短时有效，只能放在 WebSocket 首个 JSON 消息中；
+- 刷新页面时，只要原 Host 仍存活可申请新 ticket 并按 sequence reconnect；
+- 输出缓冲已经截断时返回明确 gap；不补造丢失字节；
+- Host 重启后旧 terminal 显示 lost，不从 Session、日志或 snapshot 恢复；
+- close、workspace switch 和 Host shutdown 会终止拥有的进程树。
+
+terminal 字节不会进入 Workbench SSE、Thread transcript、diagnostics、release stdout/stderr 或持久设置。
+
+## API 客户端变化
+
+自定义 v0.3.0 Web 客户端升级时应改用
+[`v0.3.1 OpenAPI`](../architecture/v0.3.1-web-api.yaml)：
+
+- active workspace/session/resource 请求携带 `workspaceId` 和 `expectedContextRevision`；
+- mutation 的 `requestId` 是 UUID；session command 仍携带 `expectedSessionId`；
+- 新增 Workspace registry/session summary、files、Git、review、terminal REST 资源；
+- terminal 使用独立 `orion-terminal-v1` WebSocket，不能从 SSE 读取 terminal output；
+- `workspace_resource_invalidated` 只提示按 revision 重取，不携带文件、Diff 或 terminal 内容。
+
+不要在 409 后盲目重放旧 body；先获取新 bootstrap，确认用户仍希望对同一目标执行，再生成新的
+context-bound mutation。只有 byte-equivalent body 才能复用原 requestId。
+
+## 回滚到 v0.3.0
+
+1. 关闭浏览器并停止 v0.3.1 Host，等待所有 terminal 进程退出；如有异常，先核对进程所有权再处理。
+2. 保留一份 v0.3.1 WorkspaceRegistry/layout preference 备份以便排查；v0.3.0 不依赖这些数据。
+3. 使用升级前备份恢复 `orion.json`（如果升级期间修改过 Settings）。
+4. 安装并启动确切的 v0.3.0 artifact，再显式选择原 Workspace/Session。
+5. 验证 Thread history、当前模型、Goal/Plan 和 pending approval；不要从 terminal 输出重建历史。
+
+回滚不会自动恢复已关闭或 lost 的 terminal，也不应删除 v0.3.1 创建的项目文件。WorkspaceRegistry
+和布局偏好不是 Session 权威源；旧版本忽略它们不代表数据被删除。
+
+## 升级验证
+
+按 [`v0.3.1 Web E2E 资格计划`](../test/v0.3.1-web-workbench-e2e-plan.md)执行
+WEB31-P0-01..12。只有 source-clean exact-tarball、真实 Chrome、Node 22.12/24/26 和最终 receipt
+均为 GO，才能把当前候选标记为发布完成。

package/docs/orion.example.json

@@ -5,7 +5,7 @@
       "id": "my-provider",
       "displayName": "My OpenAI-compatible Provider",
       "baseUrl": "https://your-endpoint.example/v1",
-      "apiKey": "sk-REPLACE_WITH_YOUR_KEY",
+      "apiKey": "$ORION_CODE_API_KEY",
       "protocol": "openai-completions"
     }
   ],
@@ -41,7 +41,14 @@
   "allowedTools": [],
   "projects": {
     "/absolute/path/to/project": {
-      "compactInstructions": "Retain architecture decisions, failed verification, and release receipts."
+      "compactInstructions": "Retain architecture decisions, failed verification, and release receipts.",
+      "defaultEffort": "medium"
+    }
+  },
+  "web": {
+    "appearance": {
+      "theme": "system",
+      "motion": "system"
     }
   },
   "ui": {

package/docs/plan/v0.3.0-node-runtime-compatibility-plan.md

@@ -0,0 +1,57 @@
+# Orion Code v0.3.0 Node Runtime Compatibility Plan
+
+> 状态：实现完成；本地候选兼容矩阵 `GO`，待 source-clean 发布门禁
+> 基准日期：2026-08-28
+> 目标：让源码构建、npm 安装包、CLI/TUI、Web Host、原生 SQLite 与发布证据在同一套明确的
+> Node 版本合同下工作。
+
+## 1. 支持范围
+
+依据 Node.js 官方 [release schedule](https://github.com/nodejs/Release#release-schedule)，本版本采用：
+
+| Node 主版本 | v0.3.0 定位               | 最低版本 | 说明                           |
+| ----------- | ------------------------- | -------- | ------------------------------ |
+| 22          | supported maintenance LTS | 22.12.0  | 受 Vite 7 工具链最低版本约束   |
+| 24          | preferred LTS             | 24.0.0   | 新生产安装的首选版本           |
+| 26          | supported Current         | 26.0.0   | 覆盖当前主流开发环境与 ABI 147 |
+
+Node 21/23/25 等短生命周期奇数版本不进入发布承诺。`engines.node` 是安装合同，不能超前于
+真实测试矩阵。Node 20 已结束上游维护，并且当前 `better-sqlite3@12.10.x`
+不再提供 Node 20 预构建产物；因此它只属于历史证据，不属于 v0.3 的安装或发布合同。
+
+## 2. 实现合同
+
+1. `package.json` 与 `npm-shrinkwrap.json` 必须声明完全相同的 Node 范围。
+2. dependency policy 必须在 22/24/26 上执行真实 `better-sqlite3` open、SQL query、
+   `sqlite-vec` load 与 `vec0` virtual table probe。
+3. GitHub Actions 的 source build/test、exact-tarball runtime 和 critical Web E2E 三个矩阵都必须
+   包含三个版本，且不允许 skip 记为 pass。
+4. Runtime/Web E2E/最终 ReleaseReceipt 必须要求三个 Node receipt 全部存在、全部为 `GO`，并绑定
+   同一个 tarball SHA、artifact receipt digest、runner digest 与 installed target digest。
+5. 本地多版本验证必须使用隔离安装目录，不能用一个 Node 版本编译的 `node_modules` 冒充另一个 ABI。
+6. CLI 的 `#!/usr/bin/env node` 启动方式保持版本管理器无关；产品代码不得硬编码某个 Node 安装路径。
+
+## 3. 真实验收
+
+对一次冻结的 `@orion-agents/orion-code@0.3.0` tarball，在 Node 22/24/26 分别执行：
+
+- clean install，确认 npm engine 无拒绝；
+- package identity、`orion --version`、`orion --help` 与公共 exports；
+- `better-sqlite3`/`sqlite-vec` 原生语义探针；
+- TUI、terminal、print、Web Host；
+- Goal、subagent、Skill、MCP、Compact/resume 旅程；
+- critical real-Chrome Web/Settings 旅程。
+
+硬判定：任一版本缺失、跳过、ABI load 失败、receipt 未绑定同一 tarball，最终结果均为 `NO_GO`。
+
+## 4. 回归门禁
+
+- `npm run build`
+- `npm test -- --coverage --runInBand`
+- `npm run deps:check -- --policy-only`
+- `npm run test:runtime-matrix`
+- `npm run test:web-e2e:critical`
+- receipt contract tests and workflow static checks
+
+最终测试环境、精确 tarball SHA 与每个 Node receipt 写入独立测试报告；本计划不把意图或单版本成功
+当作兼容性完成证据。