@orion-agents/orion-code 0.2.0 → 0.3.0

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/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 写入独立测试报告；本计划不把意图或单版本成功
+当作兼容性完成证据。