@visual-z/xeno 0.8.4 → 0.9.1

package/bin/xeno.exe

@@ -0,0 +1,26 @@
+# xeno placeholder (docs/tasks/feat-binary-release.md). No shebang on purpose:
+# npm's Windows cmd-shim then execs bin/xeno.exe directly once postinstall has
+# replaced this file with the real binary. POSIX shells run a file without a
+# shebang as a sh script, which is what happens when postinstall never ran
+# (`bun add -g` skips dependency scripts unless the package is trusted).
+# Platform keys must match scripts/binary-targets.ts.
+self=$0
+while [ -h "$self" ]; do
+  link=$(readlink "$self")
+  case $link in /*) self=$link ;; *) self=$(dirname "$self")/$link ;; esac
+done
+main=$(cd "$(dirname "$self")/.." && pwd -P)
+case $(uname -s) in Darwin) os=darwin ;; Linux) os=linux ;; *) os=$(uname -s) ;; esac
+case $(uname -m) in arm64|aarch64) arch=arm64 ;; x86_64|amd64) arch=x64 ;; *) arch=$(uname -m) ;; esac
+libc=
+if [ "$os" = linux ] && { ls /lib/ld-musl-* >/dev/null 2>&1 || ldd --version 2>&1 | grep -qi musl; }; then libc=-musl; fi
+# An x64 shell under Rosetta on Apple Silicon: prefer the native arm64 build.
+if [ "$os" = darwin ] && [ "$arch" = x64 ] && [ "$(sysctl -n sysctl.proc_translated 2>/dev/null)" = 1 ]; then arch=arm64; fi
+key=$os-$arch$libc
+# npm nests optional dependencies under the main package; bun hoists them beside it.
+for bin in "$main/node_modules/@visual-z/xeno-$key/xeno" "$main/../xeno-$key/xeno"; do
+  if [ -x "$bin" ]; then exec "$bin" "$@"; fi
+done
+echo "xeno: no binary for $key was installed." >&2
+echo "Reinstall without --omit=optional: npm i -g @visual-z/xeno" >&2
+exit 1

package/install.cjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Postinstall for @visual-z/xeno (docs/tasks/feat-binary-release.md).
+//
+// Finds this machine's platform package among the optionalDependencies and
+// hard-links its binary over the bin/xeno.exe placeholder, so `xeno` execs the
+// native program directly with no Node or shell process in between. Same
+// layout as Claude Code's npm wrapper. The photon wasm goes beside it because
+// the image module looks for it next to the executable.
+//
+// If this never runs (`bun add -g` skips dependency scripts unless trusted),
+// the placeholder is itself a POSIX sh launcher that finds the same binary.
+// A failure here never fails the install: the placeholder still works.
+//
+// PLATFORMS must match scripts/binary-targets.ts; test/binary-release.test.ts
+// enforces that.
+
+const { spawnSync } = require("child_process");
+const { copyFileSync, existsSync, linkSync, renameSync, unlinkSync, chmodSync } = require("fs");
+const { arch } = require("os");
+const path = require("path");
+
+const PREFIX = "@visual-z/xeno";
+const PLATFORMS = {
+  "darwin-arm64": { pkg: PREFIX + "-darwin-arm64", bin: "xeno" },
+  "darwin-x64": { pkg: PREFIX + "-darwin-x64", bin: "xeno" },
+  "linux-arm64": { pkg: PREFIX + "-linux-arm64", bin: "xeno" },
+  "linux-x64": { pkg: PREFIX + "-linux-x64", bin: "xeno" },
+  "linux-arm64-musl": { pkg: PREFIX + "-linux-arm64-musl", bin: "xeno" },
+  "linux-x64-musl": { pkg: PREFIX + "-linux-x64-musl", bin: "xeno" },
+  "win32-arm64": { pkg: PREFIX + "-win32-arm64", bin: "xeno.exe" },
+  "win32-x64": { pkg: PREFIX + "-win32-x64", bin: "xeno.exe" },
+};
+const WASM = "photon_rs_bg.wasm";
+
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  // glibcVersionRuntime is absent on musl; ld-musl is the fallback when report is unavailable (Bun).
+  const report = typeof process.report?.getReport === "function" ? process.report.getReport() : null;
+  if (report?.header && "glibcVersionRuntime" in report.header) return false;
+  if (report?.header) return true;
+  return ["/lib/ld-musl-x86_64.so.1", "/lib/ld-musl-aarch64.so.1"].some(file => existsSync(file));
+}
+
+function platformKey() {
+  let cpu = arch();
+  // An x64 Node under Rosetta on Apple Silicon: prefer the native arm64 build.
+  if (process.platform === "darwin" && cpu === "x64") {
+    const translated = spawnSync("sysctl", ["-n", "sysctl.proc_translated"], { encoding: "utf8" });
+    if (translated.stdout?.trim() === "1") cpu = "arm64";
+  }
+  return `${process.platform}-${cpu}${isMusl() ? "-musl" : ""}`;
+}
+
+// Hard link first: instant and no second copy of a ~90 MB file. Copy across filesystems.
+function place(source, dest) {
+  const temp = dest + ".tmp-" + process.pid;
+  try { linkSync(source, temp); } catch { copyFileSync(source, temp); }
+  // rename replaces atomically on POSIX, so the placeholder is never missing; Windows refuses to rename over a file.
+  if (process.platform === "win32") { try { unlinkSync(dest); } catch { /* nothing to replace */ } }
+  try { renameSync(temp, dest); }
+  catch (error) { try { unlinkSync(temp); } catch { /* already gone */ } throw error; }
+  if (process.platform !== "win32") chmodSync(dest, 0o755);
+}
+
+function main() {
+  const key = platformKey(), info = PLATFORMS[key];
+  if (!info) {
+    console.error(`[xeno postinstall] Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}`);
+    return;
+  }
+  let dir;
+  try { dir = path.dirname(require.resolve(info.pkg + "/package.json", { paths: [__dirname] })); }
+  catch {
+    console.error(`[xeno postinstall] ${info.pkg} is not installed (--omit=optional, or its download failed).`);
+    console.error("  Reinstall @visual-z/xeno to fetch it.");
+    return;
+  }
+  try {
+    place(path.join(dir, info.bin), path.join(__dirname, "bin", "xeno.exe"));
+    if (existsSync(path.join(dir, WASM))) place(path.join(dir, WASM), path.join(__dirname, "bin", WASM));
+  } catch (error) {
+    console.error(`[xeno postinstall] Could not place the binary: ${error.message}`);
+    console.error("  xeno still starts through its launcher, one process slower.");
+  }
+}
+
+if (require.main === module) main();
+module.exports = { PLATFORMS, platformKey };

package/package.json

@@ -1,60 +1,30 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "license": "UNLICENSED",
-  "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",
   "bin": {
-    "xeno": "src/apps/cli.ts"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "CHANGELOG.md",
-    "docs/install.md",
-    "docs/providers.md",
-    "docs/app-server.md",
-    "docs/foundations.md",
-    "docs/research/foundation-clients-2026-10-09.md",
-    "docs/research/foundation-editing-2026-10-09.md",
-    "docs/research/foundation-network-2026-10-09.md",
-    "docs/research/foundation-workflow-2026-10-09.md"
-  ],
-  "engines": {
-    "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/visual-z/xeno.git"
+    "xeno": "bin/xeno.exe"
   },
   "scripts": {
-    "test": "bun test",
-    "typecheck": "bun run scripts/typecheck.ts",
-    "check": "bun run scripts/check-boundaries.ts",
-    "gate": "bun test && bun run typecheck && bun run scripts/check-boundaries.ts",
-    "eval:test": "bun test ./eval/test",
-    "gate:full": "bun run gate && bun run eval:test",
-    "verify-red": "bun run scripts/verify-red.ts",
-    "regen-golden": "bun run scripts/regen-golden.ts",
-    "measure": "bun run scripts/measure-handoff.ts",
-    "agent": "bun run src/apps/cli.ts"
+    "postinstall": "node install.cjs"
   },
-  "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/bun": "latest"
-  },
-  "dependencies": {
-    "@agentclientprotocol/sdk": "1.7.0",
-    "@anthropic-ai/sdk": "^0.127.0",
-    "@earendil-works/pi-ai": "0.99.1",
-    "@modelcontextprotocol/client": "2.3.1",
-    "@opentui/core": "0.5.14",
-    "@silvia-odwyer/photon-node": "0.3.4",
-    "ajv": "8.20.0",
-    "grok-mermaid": "0.2.3",
-    "highlight.js": "10.7.3",
-    "marked": "18.0.11"
+  "optionalDependencies": {
+    "@visual-z/xeno-darwin-arm64": "0.9.1",
+    "@visual-z/xeno-darwin-x64": "0.9.1",
+    "@visual-z/xeno-linux-arm64": "0.9.1",
+    "@visual-z/xeno-linux-x64": "0.9.1",
+    "@visual-z/xeno-linux-arm64-musl": "0.9.1",
+    "@visual-z/xeno-linux-x64-musl": "0.9.1",
+    "@visual-z/xeno-win32-arm64": "0.9.1",
+    "@visual-z/xeno-win32-x64": "0.9.1"
   },
+  "files": [
+    "bin/xeno.exe",
+    "install.cjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   }

package/docs/app-server.md

@@ -1,115 +0,0 @@
-# 会话控制接口与 TUI 工作台
-
-状态：实验性 `xeno-control/0.1`。TUI 和适配器共用一个 `SessionControl`、一个实际 Session 和同一份 append-only 日志。协议借鉴 Codex App Server 的生命周期，**不声明与 Codex v2 wire format 兼容**。没有新增模型调用、第二个执行进程或独立目标数据库。
-
-## 从源码使用
-
-```bash
-bun run agent app-server schema
-bun run agent app-server --model openai-codex/gpt-6-luna
-bun run agent --control-socket /tmp/xeno-control-private/control.sock
-```
-
-第一条只打印版本、请求参数 schema、通知清单及限制，不加载模型凭证。第二条用 stdin/stdout 双向 JSONL；诊断在 stderr。启动会话仍采用原有的凭证、工具权限、`--session` / `--continue` 和 `--acceptance-file` 参数。提示从 `turn/start` 提交，不能作为位置参数。结构化模式不构造 TUI，也不发送 OSC。
-
-第三条正常启动 TUI，Unix socket 连接到它当前的同一个会话。父目录必须由当前用户拥有且权限为 0700；不存在时自动创建，socket 为 0600。已有路径拒绝覆盖。这里没有 TCP、Web 面板或远程认证服务。每个适配器都是具有当前用户本地控制能力的客户端，可启动工具和答复审批。
-
-## 初始化与恢复
-
-每行一个 JSON 对象；省略 `jsonrpc`。请求必须有字符串或安全整数 `id`，响应返回相同 `id` 及 `result` 或 `error`。只有 `initialized` 是客户端无 id 通知。所有其他方法必须等初始化完成。
-
-```json
-{"id":1,"method":"initialize","params":{"clientInfo":{"name":"my-adapter","version":"0.1"}}}
-{"method":"initialized"}
-```
-
-读取 initialize 的 `result.threadId` 和 `result.streamId` 后，提交：
-
-```json
-{"id":2,"method":"thread/subscribe","params":{"threadId":"<returned-threadId>"}}
-{"id":3,"method":"turn/start","params":{"threadId":"<returned-threadId>","input":"Inspect the failing test and report the evidence."}}
-```
-
-通知可以早于对应请求响应，客户端应按 request id 关联响应。`thread/subscribe` 先订阅，再返回快照；应先缓存这期间的通知，拿到快照后只应用同一 streamId 且 sequence 大于快照 sequence 的通知。sequence 是控制器生命周期内递增的通知序号，包含瞬时输出，不能作为持久日志地址。
-
-- `threadId` 是规范化绝对 session 目录路径的 SHA-256。同路径冷恢复保持身份；移动或复制目录会改变身份，不是可携带 UUID。
-- `streamId` 每个活控制器生成一次。重启会变化；`turnId` 等于这一轮原始 user event ID；steering 引用这个请求，不另开目标。
-- `item/completed` 在持久 append 成功后发送 `{node,id,type}`。完整事件通过 `item/read` 读取，唯一地址是 node + event id。
-- 断线、序号跳跃或 streamId 改变：重新初始化、订阅，消费返回快照，再分页读 `item/list` / `item/read`。可给订阅传 `after:{streamId,sequence}`；游标与当前快照不同就返回 `resyncRequired:true`。
-- 不保存、重放瞬时文本 delta，不重放命令。控制请求不具备幂等重试保证；丢失 `turn/start` 响应时先查看当前 turn 和日志，不能盲目重发。
-- TUI 切换 Session 后，旧 threadId 拒绝继续控制，适配器应建立新连接重新初始化。stdio app-server 另外由 SessionHub 拥有多个 Session；每个 durable log 只有一个活执行者，path/basename/threadId 别名的并发冷恢复收敛到同一个拥有者。
-
-## 方法与事件
-
-`app-server schema` 输出的 `methods` 是实际入参验证器共用的 schema；目前不是所有响应类型的完整 JSON Schema/生成式 SDK。
-
-| 方法 | 除 threadId 外的参数 | 结果 / 作用 |
-|---|---|---|
-| `thread/list` | 无 | 当前 workspace 的保存会话与活拥有者身份 |
-| `thread/new` | 可选 name | 创建并返回独立会话快照 |
-| `thread/resume` | session | 以当前 workspace 的 path/id/threadId 恢复并返回快照 |
-| `thread/fork` | 可选 name | 从 idle thread 创建新日志，保留原始 ancestry 引用 |
-| `thread/close` | 无 | 取消、等待原拥有者清理后关闭；日志保留 |
-| `thread/mode` | mode | build/plan，在 idle 共享资源检查点切换 |
-| `thread/read` | 无 | 当前目标、执行、进展、上下文和待审批快照 |
-| `thread/subscribe` | 可选 after | 订阅通知并返回快照及 resyncRequired |
-| `turn/start` | input | 开始唯一执行，返回 turnId；忙时拒绝 |
-| `turn/steer` | turnId, input | 排队，在原有模型/工具边界消费；最多 32 项 |
-| `turn/interrupt` | turnId | 取消并清理当前执行；完成由 turn/completed 确认 |
-| `approval/respond` | turnId, approvalId, choice | once / command / tool / deny；过期身份拒绝 |
-| `question/respond` | turnId, requestId, reply | reply 为 JSON 编码的结构化答案，按原问题/选择身份验证 |
-| `acceptance/accept` | requestId, criterionId | 只在 idle 显式批准本请求已声明的人验条件 |
-| `context/read` | focus，可选 offset / limit | messages / omitted / history 来源分页，不改模型输入 |
-| `item/list` | 可选 after:{node,event} / limit | 当前活动路径的日志身份分页 |
-| `item/read` | node, event | 当前活动路径上的完整日志事件 |
-
-分页 limit 为 1–100，默认 50。切换路径后旧游标可能失效，应重新获取快照。完整单条事件超过帧上限会报错；此版本不提供大事件分块下载。
-
-通知包括 `turn/started`、`turn/event`（原有 LoopEvent 的瞬时进展）、`item/completed`、`turn/completed`、`turn/error`、`turn/steeringQueued`、`approval/request`、`approval/resolved`、`question/request`、`question/resolved`、`thread/statusChanged`。每条带 threadId / streamId / sequence，活动 turn 存在时带 turnId。question 请求及答复按原始 turn、tool call、question 和 choice 身份关联；重连快照包含尚未回答的问题。`turn/completed.steeringUndelivered` 明确没有消费的排队输入；客户端不能将“已入队”显示为“已执行”。provider 抛错时仍从持久日志读取 outcome，错误通知不透出原始 provider 报文。
-
-日志是事实来源。观察者得到独立副本，修改或抛错不能改变执行。刷新 idle 快照沿原有验收观察边界重新检查工作区，可能追加失效证据；这不提交提示或调用模型。活动目标和快照游标采用同一个已发布事件边界；切段期间无法一致读取时返回刷新错误。
-
-## 审批、断连与限制
-
-审批是同一个权限请求；TUI 或适配器答复后另一端的待审批状态同时结束。取消清理审批承诺，不允许晚到 provider 响应覆盖取消状态或继续执行工具。stdio 是独立会话的主控制连接：EOF/关闭会拒绝审批并取消执行。Unix socket 客户端断开只撤掉该观察者，TUI 继续拥有当前审批与执行。
-
-输入单帧上限 1 MiB，每连接最多排队 32 请求，输出缓冲上限 2 MiB，socket 最多 32 客户端，SessionHub 最多 32 个活会话（包含尚未完成的打开请求）；这些是容量假设，不是模型策略阈值。超限断开或返回有界错误。错误码：`-32600` envelope、`-32601` 未知方法、`-32602` 参数、`-32700` JSON、`-32000` 生命周期/执行冲突、`-32001` 传输容量、`-32002` 响应过大。快照本身过大时使用分页 inspector；超大目标详情需要后续协议扩展。
-
-## 类型化客户端与 ACP
-
-源码客户端 `src/runtime/control-client.ts` 验证发送参数、响应 envelope、方法结果与通知身份；限制帧、在途请求和超时，不自动重发请求。适配器负责接入字节流并在 EOF 调用 close：
-
-```ts
-import { ControlClient } from "./src/runtime/control-client.ts";
-
-const client = new ControlClient(line => transport.write(line), { close: () => transport.close() });
-transport.onText(text => client.feed(text));
-transport.onEnd(() => client.close());
-const initial = await client.initialize("my-adapter", "0.1");
-const other = await client.request("thread/new", { name: "Investigation" });
-const unsubscribe = client.onNotice(notice => render(notice), other.threadId);
-const subscription = await client.request("thread/subscribe", { threadId: other.threadId });
-await client.request("thread/mode", { threadId: other.threadId, mode: "plan" });
-await client.request("turn/start", { threadId: other.threadId, input: "检查实现并列出证据" });
-```
-
-transport/render 为适配器自行提供的接口；订阅期间仍需使用上述 snapshot/sequence 恢复规则。respondQuestion 便利方法接收完整 QuestionReply，包含 request_id、turn_id 与按稳定 id 回答的 answers；外层请求同样指定 threadId、turnId、requestId。
-
-`bun run agent acp --agent build` 提供官方 ACP SDK 的 stdio JSON-RPC 入口，与 xeno-control 的 wire format 分开。支持 initialize、new/load session、prompt/cancel、Plan/Build 模式、文本与工具进展、客户端权限请求及其 MCP 配置。所有 session 固定在启动 workspace，外部 cwd 具名拒绝；load 不发送模型提示。支持 elicitation 的客户端可以回答 question，否则工具返回不可用。stdout 只含协议，诊断走 stderr；EOF 取消并等待所有正在打开和活跃会话清理。此入口沿用现有配置与权限，不自动安装模型、MCP 或语言服务器。
-
-## TUI 与终端状态
-
-常驻 Goal 区展示原始目标、验收状态、执行状态和观察/重试数。`/control` 在右侧栏打开同一会话的面板，保留底部输入框和草稿；窄窗口改为消息区内的右侧抽屉，尺寸不足时提示放大。F6 切换面板与编辑器焦点，Esc 回到编辑器并保留面板，Q 关闭并恢复状态侧栏。面板有焦点时，Tab 切 Goal / Progress / Context Lens，左右键切上下文来源/省略事件/handoff 恢复引用，上下键或 PageUp/PageDown 翻阅，R 刷新，I 取消，A 选择当前声明的人验条件；其它文字输入会回到原编辑器。长目标和证据换行显示，缩放保留页签、滚动和草稿。
-
-远程开始的普通 turn 会更新当前 TUI，并可在面板取消。TUI 输入的 steering 在同一 turn 的原有边界消费，followup 等原 turn 释放后执行；远程取消也把未发送内容归还编辑器。既有隔离 skill / shell 保留各自执行入口，当前协议不新增远程 skill/shell 方法。
-
-无验收合同保持 `unverified`；模型结束 `model_end` 不等于目标 `verified`。Progress 的观察、产物、验收、新诊断和原样重试均带日志来源；数量不是完成百分比。Context Lens 复用实际 dispatch 的投影，只过滤检查视图，不修改 frozen prefix、handoff 或消息。
-
-OSC 7501 遵循 [Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status) 的状态、身份及 UTF-8 base64 消息语法：
-
-- `XENO_PROGRAM_STATUS=auto`（默认）：TTY 探测成功后才发送状态；未回复时只有一次探测，不发送报告。
-- `XENO_PROGRAM_STATUS=1`：显式开启；`0`：关闭。管道始终关闭；auto 在 tmux/screen 内关闭，可用 1 显式覆盖。
-- running → working，审批/认证/提问 → blocked + kind，取消 → idle，失败 → error。结束使用 done，同时固定消息明确是否通过目标合同；待人验保持 blocked。
-- 不发送用户提示、模型输出、凭证或假百分比。每进程只操作自己的 `xeno-<pid>` 记录；退出清理瞬时记录，保留规范要求可留存的 done/error。
-
-自动验证包含真实 TUI、真实 Unix socket、CLI JSONL 与 PTY 探测；不等同于作者在所有终端上的视觉验收。配对实验及真实历史语料统计见[研究报告](research/session-control-evaluation-2026-10-08.md)。

package/docs/foundations.md

@@ -1,88 +0,0 @@
-# 基础工作流
-
-保留 `coding` 的十工具默认配置与老会话能力边界。新建会话选择 `--agent build`、`--agent plan` 或 `--tool-profile foundation`，启用 question、apply_patch、diff、webfetch、websearch、format，以及配置存在时的 lsp。`--tools` 仍为严格白名单，`--no-tools` 不被模式或角色自动覆盖。
-
-```bash
-bun run agent --agent build "实现并验证这个功能"
-bun run agent --agent plan "先检查实现并提出计划"
-bun run agent --tool-profile foundation "读取网站并核对项目"
-bun run agent --output-schema result.schema.json --output-last-message result.json -p "返回符合 schema 的 JSON"
-bun run agent review branch main
-bun run agent acp --agent build
-```
-
-## 模式与角色
-
-`/plan` 与 `/build` 在 idle 时切换，改变真实工具准入和冻结前缀，追加检查点。Plan 允许 read 与 harness 的 note/question，不执行 shell、写文件或任意扩展代码。它是能力边界，沿用 xeno 既有的无 OS sandbox 设计。明确的工具白名单和配置 deny 保持有效。
-
-`/agent` 列出角色，`/agent <name>` 选择。内置 build/plan/reviewer；用户文件为 `~/.xeno/agents.json`，已信任项目可用 `.xeno/agents.json`。`XENO_CONFIG_DIR` 改变用户配置目录。低到高为内置、用户、项目；相同角色按整个字段覆盖，不拼接半份 tools/model。明确 CLI 参数优先，模型、thinking、权限、说明和预算共同应用于一个检查点。失败保留旧配置；冷启动保存角色名称，按当前文件及项目信任重新解析。缺失或撤销信任的项目角色具名报错。
-
-```json
-{
-  "profiles": [{
-    "name": "investigator",
-    "description": "检查实际证据并提出方案",
-    "mode": "plan",
-    "instructions": "以仓库和工具回执为依据，指出未知项。",
-    "tools": { "profile": "foundation", "exclude": ["websearch"] },
-    "permissions": [{ "action": "deny", "tool": "read", "paths": ["private/**"] }],
-    "budget": { "maxTurns": 20, "timeBudgetMs": 60000 }
-  }]
-}
-```
-
-maxTurns 为硬限制；timeBudgetMs 沿用剩余时间提示语义，不是强制截止。结构化 question 最多三个问题，有稳定 question/choice id，支持单选、多选、自定义文字。TUI、控制客户端或支持 elicitation 的 ACP 客户端答复；缺少答复入口时返回不可用，取消与晚到答复不能串到下一次调用。
-
-## 工具配置
-
-用户 `~/.xeno/foundation.json` 与已信任项目 `.xeno/foundation.json` 的同名顶层字段整体替换。配置允许五个字段：mcp、webSearch、formatters、lsp、permissions。未知字段或无效 schema 在发布资源前报错。配置命令不会自动安装可执行文件。
-
-```json
-{
-  "mcp": {
-    "local": { "transport": "stdio", "command": "my-mcp-server", "args": [], "timeoutMs": 10000 },
-    "remote": { "transport": "http", "url": "https://example.com/mcp", "oauth": true }
-  },
-  "webSearch": { "provider": "brave", "apiKeyEnv": "BRAVE_API_KEY" },
-  "formatters": [{ "name": "prettier", "extensions": [".ts", ".tsx"], "command": ["prettier", "--write", "$FILE"] }],
-  "lsp": [{ "name": "typescript", "command": ["typescript-language-server", "--stdio"], "extensions": [".ts", ".tsx"], "languageId": "typescript" }],
-  "permissions": [
-    { "action": "deny", "tool": "*", "paths": ["private/**"] },
-    { "action": "allow", "tool": "exec_command", "commandPrefix": ["git", "status"] }
-  ]
-}
-```
-
-这些命令是假定已安装工具的配置示例。可在 `/reload` 后应用，角色/模式切换同样走资源拥有者。解析、发现和模型选择先完成；只有旧 integration 完成清理才发布新检查点。staging 的协议握手可能短暂存在，但业务调用仍只有已发布的执行拥有者；失败丢弃新资源，不重放旧调用。
-
-权限保持首匹配规则；配置 deny 优先于会话记忆的批准。路径匹配归一化真实资源，包括 symlink 指向；read 的资源判定也适用于 query、搜索、diff 和 LSP。grep/find/ls 在读取内容前过滤资源。`.env`、`.env.*` 默认请求批准，`.env.example` 保持普通读取。commandPrefix 只匹配完整的字面 argv 前缀，组合 shell、重定向或插值不会借此前缀批准整个程序。
-
-## 联网与 MCP
-
-webfetch 参数为 `{url,format?,timeout?}`，format 可为 markdown/text/html，timeout 为 1–120 秒。流式响应受 5 MiB 限额，逐跳验证重定向；原始内容存观察工件，提取的正文是可重算投影。websearch 参数为 `{query,count?}`，只使用明确配置的 Brave 或 Exa；未配置或无密钥时直接说明不可用。`--offline` 禁止这些工具的网络请求与 HTTP MCP 自动连接。
-
-`/mcp`、`/mcp status` 查看状态，`/mcp login <server>` 显式发起 OAuth，`/mcp logout <server>` 清理凭据。HTTP 也可用 bearerTokenEnv 或 headersEnv；密钥保存在环境或私有凭据存储，不写到模型参数和日志。OAuth 使用 PKCE、state、issuer 与 loopback callback。授权/刷新在业务请求前或用户修复时进行，401/403 不自动重放业务调用。
-
-MCP 使用官方客户端的 stdio/Streamable HTTP；按 server capabilities 发布 tools、resources 和 prompts。工具经现有 tool_search 延迟发现、权限检查与 broker 执行。注解不是只读证据，Plan 不执行 MCP 工具。完整 JSON Schema 在发现时编译和冻结，无效参数在远程业务调用之前拒绝；未知关键字、引用或格式需修复配置。HTTP session 关闭会发送有界 DELETE，stdio 进程由客户端清理。
-
-## 编辑、格式化、目录规范
-
-apply_patch 参数为 `{patchText,expected_sha256?}`，语法使用 `*** Begin Patch` / `*** Add File:` / `*** Update File:` / `*** Move to:` / `*** Delete File:` / `*** End Patch`。更新和删除需要先读到实际版本，或提供路径到 SHA-256 的 expected_sha256 映射；只准备新文件时无需旧版本。多文件全部预检，提交使用现有 CAS 和补偿回滚，保留 BOM、换行与权限；`/back ... files` 复用真实检查点。
-
-format 参数为 `{paths:[...]}`，只执行配置中的 literal argv；`$FILE` 替换为绝对路径。每条命令经真实拥有者、审批、退出码与检查点执行，不会在 edit 后暗中格式化。读到新的文件版本后再生成后续编辑。
-
-启动从 Git 根到 cwd 加载目录规范。首次碰到目标文件的更深层 AGENTS.md / AGENTS.override.md 时：read / query / lsp 照常执行，规范（带来源和 scope）附在同一个结果之后；write / edit / apply_patch / format 先返回指令回执，原操作未执行，模型读到后可显式重试。同一批调用里一份规范只下发一次，后到的修改只指向先附上规范的那次调用。规范追加到原始日志并按内容指纹去重，保留冻结前缀和旧事件。
-
-## Diff、Review 与 LSP
-
-`/diff [working|last-turn|branch <base>|commit <ref>]` 查看 diff。`/review-code` 与 `xeno review` 用相同范围创建独立只读 review Session，主对话不进入 review 模型输入，主会话获得指向独立日志和不可变 premise 的回执。`/review` 仍可用于原有用户提示模板/skill，避免占名。Git 禁止 ext-diff/textconv，不改作者 index。last-turn 依据原始 applied checkpoint；未捕获的 shell/外部变化明确列为未知。
-
-lsp 参数为 `{action,path,line?,character?}`；action 为 diagnostics、definition、references、hover，位置使用零起点行号与 UTF-16 character。请求前读取实际文件并发 didOpen/didChange。诊断包含 current/stale/unversioned 等新鲜度，不把没有版本的缓存当成最新事实。取消初始化会清理进程；普通请求取消只发对应 cancelRequest。服务器 applyEdit 明确拒绝，写入须经 Patch 拥有者。
-
-## JSON 输出与客户端
-
---output-schema 支持 draft-07（默认）、2019-09、2020-12 及标准 formats；不 coercion、不填默认值、不删除额外字段。未知 schema 语义启动失败。最终输出须为纯 JSON，验证失败留下 execution_error，print stdout 不发布无效答案，CLI 退出 1；--output-last-message 仅保存完成后的最终答案。日志与 JSON 事件流仍保留实际响应和最终失败事实。
-
-多会话控制、类型化客户端与标准 ACP 的入口、恢复、权限、提问及容量限制见 [app-server.md](app-server.md)。本地 fake 模型、真实协议子进程与 PTY 验证不等同于付费供应商、外部生产服务器或作者终端的人工验收。
-
-设计依据：[联网/MCP](research/foundation-network-2026-10-09.md)、[工作流/权限/LSP](research/foundation-workflow-2026-10-09.md)、[编辑/Review/ACP](research/foundation-editing-2026-10-09.md)、[客户端与输出](research/foundation-clients-2026-10-09.md)。

package/docs/install.md

@@ -1,244 +0,0 @@
-# Install xeno
-
-Published as `@visual-z/xeno`. The license is `UNLICENSED`: the package is
-public to read and install, and no right to reuse the code is granted.
-
-```bash
-npm i -g @visual-z/xeno    # or: bun add -g @visual-z/xeno
-```
-
-The installed `xeno` still runs with Bun (below). Installing from a
-checkout works the same way and is described after it.
-
-## Bun, not Node
-
-The entry point is `src/apps/cli.ts` with `#!/usr/bin/env bun`. The
-process uses Bun APIs (`Bun.file`, `Bun.spawn`, `Bun.spawnSync`,
-`for await (const line of console)`). Those are why the runtime is Bun.
-
-`engines.bun` is `>=1.3.0` (required by the OpenTUI renderer, D20). This checkout was run on **Bun 1.3.10**.
-Node is untested. That is a fact about this tree, not a promise that
-Node support is coming.
-
-Install Bun from https://bun.sh.
-
-## From a checkout
-
-```bash
-git clone <this-repo> xeno
-cd xeno
-bun install
-```
-
-`bun install` pulls the provider SDKs, OpenTUI and its platform renderer,
-Markdown, syntax highlighting, Mermaid, Photon image processing, and TypeScript tooling.
-The exact versions are in `package.json` and `bun.lock`.
-
-OpenTUI supplies the native renderer through its platform dependencies.
-Clipboard integration uses terminal OSC 52 and platform commands; the old
-vendored Pi native helpers are no longer packaged. Release package checks run
-on macOS arm64; they do not establish Linux or Windows device acceptance.
-
-Run the CLI without linking:
-
-```bash
-bun src/apps/cli.ts --help
-```
-
-Or put `xeno` on your PATH from this checkout:
-
-```bash
-bun link
-```
-
-Then, in any directory:
-
-```bash
-xeno --help
-xeno --list-models
-```
-
-`bun link` writes a shim that executes the `bin` field
-(`src/apps/cli.ts`) with Bun. It does not copy the tree.
-
-Each invocation starts a new session. `xeno -c` continues the newest one;
-`xeno -r` opens a picker. `--fresh` is a compatibility alias for the default,
-and nothing is deleted. Resume restores the saved model. An explicit
-`--model` switches at a checkpoint while keeping the original log intact.
-
-Startup loads resources and opens or restores the session. Workspace snapshots
-are deferred until file tools need them, so opening an editor does not scan the
-whole project. Slow initialization shows its current stage; Ctrl+C cancels it
-and restores the terminal. Start inside the intended project or pass
-`--workspace <path>`.
-
-## Updates
-
-xeno says when a newer version is published. It never installs one on its
-own: the notice names the command. Typing `/update` is how you ask it to
-install (below).
-
-```
-xeno 0.4.0 is available (you have 0.3.0)
-  bun add -g @visual-z/xeno@latest
-```
-
-The command follows where this copy is installed: `bun add -g` under
-`~/.bun/install/global/`, `npm i -g` under an npm global prefix
-(`…/lib/node_modules/`, or `…\npm\node_modules\` on Windows). Anywhere else
-the notice points to this file. A checkout updates with `git pull`.
-
-To update now, type `/update` in the TUI. It checks the registry and, when
-a newer release exists and xeno was installed with bun or npm, runs the
-command from the notice pinned to that exact version (for example
-`bun add -g @visual-z/xeno@0.7.1`). The status line shows the target version,
-elapsed time against a 3-minute limit, and the package manager's latest output
-line; the editor stays usable. Success says `Updated xeno A → B. Restart xeno
-to use it.` — the running session keeps the old code until you restart. A
-failure says why (exit code or timeout, with the package manager's last lines)
-and repeats the command to run yourself. An unwritable install directory is
-refused before anything runs. Other install locations and checkouts are never
-installed into; they get the notice or `git pull` advice.
-
-To check without installing:
-
-```sh
-xeno update --check
-```
-
-The explicit check bypasses the daily cache, `updateCheck: false`, the
-automatic-check environment switches, and CI suppression. It reports the
-current version and the result, including a failed query; a stale cache is
-never presented as a successful fresh check. A successful query refreshes
-the same cache used by startup. Repeated checks while a request is running
-share that request. `xeno update --check` never installs, and needs no model
-credential or session.
-
-`--offline` / `XENO_OFFLINE` still prevent network access. Source checkouts
-explain that they update with `git pull` instead of querying npm. Bare
-`xeno update` and `xeno update --extensions` retain their existing extension
-package behavior; do not combine `--check` with package sources, `--local`
-or `--extensions`.
-
-- **Request.** `GET https://registry.npmjs.org/-/package/@visual-z%2fxeno/dist-tags`
-  (an 18-byte answer). If that fails, `GET …/@visual-z%2fxeno/latest`.
-  `npm_config_registry` replaces the host. The timeout is 3 seconds.
-- **What the registry learns.** Your IP address, the time, the package name
-  and Bun's default `User-Agent` (`Bun/<version>`). No identifier, no query
-  string, nothing from your session.
-- **How often automatically.** At most once every 24 hours. The time and the version seen
-  are kept in `~/.xeno/update-check.json`. A failed attempt is recorded too,
-  so a closed network is not retried on every start.
-- **When.** In the background after the editor opens. Startup never waits for
-  it, and quitting cancels it. A version found during a session is shown only
-  while that session is still empty. Otherwise it waits for the next start,
-  so it never interrupts a turn.
-
-Background checks send nothing when any of these holds (the explicit manual
-check described above is a separate action):
-
-- `--offline` or `XENO_OFFLINE=1`
-- `XENO_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` is set (to anything but empty, `0` or `false`)
-- `"updateCheck": false` in `settings.json` (*Check for updates* in `/settings`)
-- `CI` or `CONTINUOUS_INTEGRATION` is set, by the same rule
-- the run is not the interactive app: `-p`, `--mode json`, `--export`, `--list-models`, `models --refresh`, package and `config` commands, `--version`
-- xeno runs from a checkout: its package root is not under `node_modules`, or has a `.git` (`bun src/apps/cli.ts`, `bun run agent`, `bun link`)
-
-## ripgrep
-
-Agents reach for `rg` in shell commands, and xeno's grep tool is faster with
-it. When neither `PATH` nor `~/.xeno/bin` has one, the interactive app
-installs ripgrep 14.1.1 into `~/.xeno/bin/rg` in the background:
-
-- **Only that build.** The archive comes from the ripgrep GitHub release and
-  must match a sha256 pinned in xeno (`src/core/ripgrep-release.ts`).
-  Anything else is discarded before extraction; only the `rg` executable is
-  unpacked.
-- **Yours wins.** `~/.xeno/bin` is appended to the end of the PATH of tool
-  commands, so an `rg` you install yourself is used instead.
-- **What the model is told.** The session's environment section says whether
-  `rg` exists in the shell at session start. A copy that finishes
-  downloading during the first session appears in the next one's line, but
-  shell commands can use it immediately.
-- **When not.** The same conditions as background update checks, except the
-  update settings: `--offline` / `XENO_OFFLINE`, `CI` /
-  `CONTINUOUS_INTEGRATION`, a non-interactive run, or running from a
-  checkout. `XENO_NO_TOOL_INSTALL` turns off only this download. Quitting
-  cancels it.
-
-Platforms: macOS arm64 and x64, Linux x64 (static musl) and arm64 (glibc).
-Elsewhere grep uses its built-in TypeScript search.
-
-## Credentials
-
-Resolution order, first match wins:
-
-1. `--api-key`
-2. `~/.xeno/auth.json` (created `0600` by `/login`)
-3. the model or provider `apiKey` in `~/.xeno/models.json`
-4. the provider's environment variable
-
-A stored entry owns that provider. The environment is not a fallback
-after a stored key fails.
-
-| Provider    | Environment variable                                      |
-|-------------|-----------------------------------------------------------|
-| anthropic   | `ANTHROPIC_API_KEY`                                       |
-| openai      | `OPENAI_API_KEY`                                          |
-| google      | `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY` |
-| deepseek    | `DEEPSEEK_API_KEY`                                        |
-| xai         | `XAI_API_KEY`                                             |
-| groq        | `GROQ_API_KEY`                                            |
-| cerebras    | `CEREBRAS_API_KEY`                                        |
-| mistral     | `MISTRAL_API_KEY`                                         |
-| openrouter  | `OPENROUTER_API_KEY`                                      |
-| zai         | `ZHIPU_API_KEY`                                           |
-| moonshotai  | `MOONSHOT_API_KEY`                                        |
-| together    | `TOGETHER_API_KEY`                                        |
-
-Interactive: export one of those, or run `/login <provider>`.
-`-p` / no tty: pass `--api-key` or export the variable. `/login` is
-not a script path.
-
-`/login claude-pro`, `/login codex`, and `/login github-copilot` start
-subscription flows (authorization-code + PKCE, or a device code for
-Copilot). They use first-party client credentials; the terms-of-service
-risk is on your account. Those flows have been tested against injected
-transports, not against a live authorization endpoint.
-
-## What a run writes
-
-In the **workspace**:
-
-```
-.xeno/sessions/<id>/   node-NNNN.jsonl, handoff-NNNN.yaml, manifest
-.xeno/blobs/           content-addressed snapshots for /back
-```
-
-That directory grows. There is no garbage collection.
-
-In **your home directory** (`~/.xeno/`, or `$XENO_CONFIG_DIR`):
-
-```
-auth.json         credentials (0600)
-settings.json     theme, thinking, defaults
-trust.json        which directories may load project settings
-models.json       optional user provider/model configuration
-models-cache.json generated catalog cache (written by `xeno models --refresh`)
-update-check.json when the last update check ran, and the newest version it saw
-keybindings.json  optional
-prompts/ skills/  optional
-```
-
-A leftover `.xeno/log` from before named sessions is not moved. Continue
-it with `--log .xeno/log`.
-
-Add this to the project's `.gitignore`:
-
-```
-.xeno/
-```
-
-## Untrusted work
-
-There is no sandbox. See the Isolation section in `README.md`.