@visual-z/xeno 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# xeno changelog
+
+## 0.2.0 — 2026-09-30
+
+- Restore saved model identity on session entry; cross-model history moves through a mechanical checkpoint.
+- Align Pi terminal input, full-screen navigation, model controls, rich content, session browsing and resource reload.
+- Add local extensions, custom UI components and explicit npm/git/local package management.
+- Export portable JSONL archives, import independent sessions, and write local terminal diagnostics.
+- Ship pinned native helpers, unify clipboard writes, and add typed extension CLI flags, model scopes, named sessions and offline export.
+- Persist thinking visibility, manage model defaults, and scope cancellable authentication to its active application.
+- Combine Pi and Models.dev into an offline catalog of 226 providers and 7,501 models, with ten native protocols and explicit exclusions.
+- Support flat, Pi and OpenCode provider configuration, private credentials and headers, local endpoints, and a separate atomic refresh cache.
+- Checkpoint changed wire profiles from the log, preserve native signatures, and render cumulative arguments for interleaved tool calls.
+
+Implementation and validation records are in the task cards under `docs/tasks/`.
+
+## 0.1.4
+
+Earlier implementation and validation records are available in `docs/PROGRESS.md`.

package/README.md

@@ -17,7 +17,7 @@ is ever summarized by a model, and nothing is ever rewritten in place.
 messages[]                             frozen system prefix + handoff + this node's events
 ```
 
-Version **0.1.3**. The on-disk session format will still change; `0.x` is that
+Version **0.2.0**. The on-disk session format will still change; `0.x` is that
 statement. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
 
 ## Install
@@ -70,8 +70,9 @@ views. Its budget-limited result and negative cases are recorded in the same rep
 neither segmentation nor the experimental adaptive rule has established a quality advantage.
 `bun run scripts/compare-harness.ts smoke --output /absolute/new/smoke-directory`
 also exercises xeno-windowed, xeno-continuous and an installed Pi CLI with shared
-confined tools, without paid model calls. Pi runs on Node through an isolated local
-tool bridge; no Pi SDK is added to the project. Its `plan` / `run` protocol freezes
+confined tools, without paid model calls. The comparison Pi CLI runs on Node through
+an isolated local tool bridge; xeno's providers use the pinned Pi AI runtime described below.
+Its `plan` / `run` protocol freezes
 source, model, task order and spending policy, including summary calls. An explicitly
 authorized `--budget unlimited` on both `plan` and `run` records costs without a local
 dollar ceiling; upstream errors stop the trial, with HTTP 402 marked as awaiting top-up.
@@ -82,15 +83,21 @@ This checks a controlled configuration, not stock Pi or an official leaderboard.
 ```
 xeno [-m <model>] [--provider <name>] [--api-key <key>]
      [-w <workspace>] [--log <dir>] [--max-turns N]
-     [--trigger N --hard N] [--list-models] [--fresh]
+     [--trigger N --hard N] [--list-models [search]] [--fresh]
+     [-c|--continue] [-r|--resume [id]] [--session path|id]
+     [--fork path|id] [--session-dir dir] [--session-id id] [--no-session]
+     [--models patterns] [--thinking level] [--mode text|json]
+     [--export session [output.html]] [--offline] [--version]
      [models --refresh]
      [--system-prompt <text-or-file>] [--append-system-prompt <text>]
      [--no-context-files|-nc]
      [--tools names] [--exclude-tools names] [--no-tools]
      [--allow-tools names] [--approve|--no-approve]
-     [--theme <name|path>]
-     [--skill <path>] [--no-skills]
-     [--prompt-template <path>] [--no-prompt-templates]
+     [--theme <name|path>] [--use-theme <name>] [--no-themes]
+     [--tui-mode regular|fullscreen]
+     [--skill <path>] [--no-skills|-ns]
+     [--prompt-template <path>] [--no-prompt-templates|-np]
+     [--extension|-e <path>] [--no-extensions|-ne]
      [-p <prompt>] [prompt...]
 ```
 
@@ -98,29 +105,53 @@ xeno [-m <model>] [--provider <name>] [--api-key <key>]
 - A prompt, or `-p` / `--print`: one shot, then exit. `-p` puts only the
   assistant's final text on stdout; the banner, usage, thinking, and tool
   lines go to stderr. Piped stdin is appended after the command-line prompt.
-- A workspace that already holds a session is resumed. `--fresh` opens a
-  second session beside it. Nothing is deleted.
+- Each invocation starts a new session, including `-p`. `--fresh` remains
+  an explicit alias. Nothing is deleted.
+- `-c` continues the newest session, or starts one if none exists. `-r`
+  opens a session picker; cancelling leaves saved sessions untouched.
+  `--session <path|id>` and `-r <id>` open a specific session.
+  A portable JSONL file creates an independent imported session in the current workspace.
+- Resume restores that session's model before consulting defaults. An
+  explicit `--model` switches through a checkpoint, preserving the original
+  log without replaying another model's thinking. Missing or ambiguous saved
+  models are reported; restore their catalog entry before resuming.
 - A leftover `.xeno/log` is not migrated; continue it with `--log .xeno/log`.
+- `--models 'deepseek/*:low,anthropic/*'` resolves ordered model scopes; an
+  explicit empty scope disables cycling. `--model id:level` sets thinking,
+  with an explicit `--thinking` taking precedence.
+- `--session-id id` creates or resumes that exact local ID. `--export` writes
+  offline HTML from a saved session or portable archive without starting an agent.
+- `--theme` can be repeated for explicit files/directories; `--use-theme`
+  selects a theme. `--no-themes` disables automatic discovery.
+- Extensions can register typed native CLI flags, including in `--help`.
+  Normal startup stays offline; `--offline` also blocks remote preparation.
 
 Slash commands that exist in the session (from `/help`):
 
 ```
 /model [id]        search models, or switch (cuts a node)
-/models refresh    fetch models.dev into ~/.xeno/models.json
+/models refresh    refresh ~/.xeno/models-cache.json; preserve models.json
 /login [provider]  choose a login method, or store an API key
 /login claude-pro|codex|github-copilot
                    subscription login (first-party client credentials)
 /logout [provider] remove a stored credential
+/scoped-models     enable, disable and order models for cycling
 /new               start a new session beside this one
 /resume [id]       search sessions, or switch to one
 /name <name>       name this session
 /session           id, path, events, usage
 /back [n [files|context]] [confirm]
-/tree              search the session tree; navigate context at an exchange boundary
+/tree              search, filter, fold, label and navigate exact session events
 /fork [n]          choose an exchange to copy into a new session
 /clone             copy the active branch into a new session
-/trust [here|parent|never]
-/settings [key v]  theme, thinking, statusBar
+/export [file]     offline HTML, or a portable archive with a .jsonl filename
+/import <file>     validate and open an archive as an independent session
+/debug [file]      write local terminal and message diagnostics
+/changelog         show bundled release notes
+/trust [once|here|parent|never]
+/reload            refresh local resources at a durable context checkpoint
+/config            search resources and edit global or project overrides
+/settings [key v]  theme, thinking, queues, viewport and editor settings
 /hotkeys           bindings in effect
 /usage  /state  /help  /quit
 ```
@@ -128,22 +159,53 @@ Slash commands that exist in the session (from `/help`):
 Type `/` for commands, templates and skills. The editor completes command
 arguments and paths. `@file` or `@"file name"` attaches a project file anywhere
 outside code literals; choosing a file keeps the prompt in the editor.
-At line start, `!cmd` runs in the workspace and sends stdout/stderr/exit to the model; `!!cmd` runs without
-sending output. During a turn, Enter queues steering (delivered after the
-current tools finish); Alt+Enter queues a follow-up for after the turn.
+`!cmd` runs in the workspace, streams output, and records it for the next model
+request. `!!cmd` records human history while excluding its output from model
+context. Neither starts a model request or requires a model credential.
+Escape cancels the command and its process group. During a turn, Enter queues
+steering after the current tools finish; Alt+Enter queues a follow-up after the
+turn, or submits immediately while idle. Alt+Up returns the entire queue to the
+editor. Settings expose independent `steeringMode` and `followUpMode` values
+of `all` or `one-at-a-time`.
 Escape interrupts; pressing Escape twice on an empty idle editor opens the tree.
 Ctrl+C clears the draft, then a quick second press exits; Ctrl+D exits an empty
 editor. Ctrl+O and Ctrl+T toggle tools and thinking throughout the history.
-
-`xeno --list-models` prints the built-in catalog (12 providers, 23 models)
-and whether a credential resolved. `xeno models --refresh` writes
-`~/.xeno/models.json`; startup never fetches.
+Ctrl+T persists `hideThinkingBlock`. `/settings` also manages new-session model
+defaults and per-model thinking overrides; clearing an override restores the
+project or global setting. `showCacheMissNotices` displays the existing prefix
+diagnostics without changing usage accounting or issuing extra model requests.
+
+`/scoped-models` changes the current session immediately; Ctrl+S saves the range.
+
+`-r` and `/resume` share a session browser: Tab changes workspace scope, Ctrl+N
+filters named sessions, Ctrl+S cycles threaded/recent/relevance ordering, Ctrl+P
+shows paths, and Ctrl+R renames. Search supports `re:<pattern>` and quoted phrases.
+Ctrl+D asks before moving an inactive session into its sibling `.trash` directory;
+the original files remain recoverable by moving that directory back. All-workspace
+discovery uses registered session roots, with no 200-session result cap.
+The tree supports Ctrl+O filter cycling, Alt+Left/Right branch folding/navigation,
+Shift+L labels, Shift+T label timestamps, and Ctrl+X copy. These actions can be rebound.
+Enter toggles a model, Ctrl+A/Ctrl+X enables/disables filtered models, Ctrl+P
+toggles a provider, and Alt+Up/Down orders enabled models. An explicit empty
+range disables cycling. `/thinking` exposes off/minimal/low/medium/high/xhigh/max
+with model capability checks; Ctrl+S saves a default for that provider/model.
+Automatic model changes clamp effort to a supported level.
+
+`xeno --list-models [search]` searches the offline union of Pi and OpenCode's
+Models.dev directory: **226 providers and 7,501 model entries** in the pinned
+snapshot. Use `provider/model` when several providers expose the same ID.
+`xeno models --refresh` atomically updates `~/.xeno/models-cache.json`;
+startup never fetches and the user's `~/.xeno/models.json` remains untouched.
+Flat catalogs, Pi `providers` and OpenCode `provider` configuration are supported.
+See [provider configuration](docs/providers.md) for local servers, model overrides,
+credentials, native cloud protocols, and explicit coverage limits.
 
 ## Credentials
 
-Order: `--api-key`, then `~/.xeno/auth.json`, then the provider's environment
-variable. A stored entry owns that provider — the environment is not consulted
-after a stored value fails.
+Order: `--api-key`, `~/.xeno/auth.json`, `models.json` provider/model credentials,
+then the provider's environment variables. A failed explicit source does not
+fall through to another account. `/login codex` uses the `openai-codex` protocol;
+ordinary OpenAI API models use `openai`.
 
 Interactive sessions can start with no key and wait for `/login`. `-p` and
 non-tty runs exit 1 and name `--api-key` or the variable; they do not mention
@@ -221,12 +283,13 @@ Shipped, not planned:
   an action/observation cycle repeats, or the request budget is nearly exhausted.
   Existing messages, the system prefix, and tool definitions stay frozen. Model
   notes remain annotations and cannot manufacture verified completion.
-- Two wire adapters (`anthropic-messages`, `openai-completions`). Both
-  stream; deltas are UI events and are not written to the log.
-- A built-in catalog of **12** API-key providers and **23** models
-  (anthropic, openai, google, deepseek, xai, groq, cerebras, mistral,
-  openrouter, zai, moonshotai, together). `~/.xeno/models.json` overrides
-  by id. Startup does not hit the network.
+- Ten native wire protocols through a pinned Pi runtime adapter, alongside the
+  three existing verified transports. Streaming text, thinking, tools and opaque
+  signatures project from the same append-only log; deltas remain UI events.
+- An offline provider/model union with **226 providers** and **7,501 entries**,
+  user overrides by provider/model, and a separate explicit-refresh cache.
+  Native protocol fixtures cover requests and responses; the directory is not
+  a claim that every listed remote account/model was tested live.
 - Sessions, resume, `/new` / `/resume` / `/name` / `/session`, `/back`
   (files, context, or both), `/tree`, read-only `branch` / `resolve`, and
   write branches in their own git worktree.
@@ -238,14 +301,46 @@ Shipped, not planned:
   Markdown, searchable pickers and settings. Durable history is a pure log
   projection across handoff boundaries. Includes tool diffs, historical folds,
   Pi dark/light palettes, `keybindings.json`, `/settings` and `/hotkeys`.
+
 - Context files: `AGENTS.md` / `CLAUDE.md` and the override chain, plus
   `--system-prompt` / `--append-system-prompt` / `-nc`.
 - Skills (`~/.xeno/skills/`, `/skill:name`) and prompt templates
   (`~/.xeno/prompts/`, `/name`). Untrusted projects do not load the
   project-level copies.
+- `/reload` refreshes local models, settings, keybindings, context files, skills,
+  templates and themes without losing the draft or active model. A changed system
+  prefix checkpoints first; unchanged resources do not create a new segment.
+  `/config` and `xeno config` share searchable resource provenance and enablement.
+  Relative resource paths resolve from the settings file that declares them;
+  project overrides cycle through inherit, load and skip. CLI paths remain explicit.
+  `/trust` opens a selector; `once` grants no persistent trust. Global
+  `defaultProjectTrust` cannot be overridden by project settings.
+  Templates support Pi's `$1`, `$@`, `$ARGUMENTS`, defaults and slices as well as
+  the existing `{{name}}` syntax. Arguments are substituted once.
+- Local TS/JS extensions can register commands, shortcuts, tools and lifecycle
+  hooks through Pi's factory protocol. Discovery, project trust and `/reload`
+  use the same resource inventory. Custom state and messages remain append-only
+  log events. See [extension boundaries and usage](docs/extensions.md).
+- Packages can come from local paths, npm or git: `xeno install <source>`,
+  `remove`, `update --extensions` and `list`. `--local` selects project scope;
+  `-e` tries a package for one invocation. Manifests, per-kind filters and trust
+  feed the same resource inventory. Normal startup stays offline.
+  See [package management](docs/packages.md).
 - `/login` for API keys and for Claude Pro/Max, Codex, and GitHub
   Copilot subscription flows. See Known gaps.
 
+Images can be attached with `@path`, a dropped image path, or Ctrl+V (files,
+image, then text). `/attachments` removes draft images; queue recall and history
+forks retain them. The log stores immutable blob references. Provider adapters
+load verified bytes for Anthropic, Chat Completions and Responses; text-only
+models receive a visible placeholder. Custom models declare `input: ["text", "image"]`
+in `models.json`. `terminal.showImages`, `terminal.imageWidthCells`,
+`images.autoResize`, `images.blockImages` and `markdown.mermaid` are configurable
+through `/settings`. Pi syntax highlighting and Mermaid use the same rendering
+path for saved replies and live output. Image tokens are estimates until provider
+usage is available. Enabling image blocking checkpoints an existing image context;
+unblocking affects new submissions, preserving historical request prefixes.
+
 ## Known gaps
 
 - **No sandbox.** See Isolation. That is a decision, not a missing feature.
@@ -258,7 +353,8 @@ Shipped, not planned:
   catalog comment on `gpt-5.5-pro` notes a `context_over_200k` tier that
   is not applied. `/usage` reports `{kind:"partial"}` when cache prices
   are missing; it does not treat a missing cache price as zero.
-- **No packages or extensions.** Skills and templates are files on disk.
+- **Package installation is separate from resource loading.** Local extensions,
+  skills and templates load from explicit, trusted filesystem sources.
   There is no installer.
 - **Bun only.** Node has not been tested.
 - **`/back` does not restore symlinks.**
@@ -270,8 +366,22 @@ Shipped, not planned:
 `docs/TUI_ARCHITECTURE.md` describes the active interaction path and verification.
 `docs/PI_PARITY.md` records deliberate differences and remaining Pi features.
 Pi's editor supports undo, not redo; an old `editor.redo` binding is diagnosed
-as unsupported rather than silently accepted. Ctrl+- and the existing Ctrl+Z
-alias invoke Pi undo.
+as unsupported rather than silently accepted. Ctrl+- invokes Pi undo.
+Ctrl+Z suspends the CLI on POSIX; `fg` restores the terminal and unsent draft.
+
+`/settings tuiMode fullscreen` uses Pi's alternate-screen viewport, transcript
+search (Ctrl+Shift+F), prompt navigation (Ctrl+Up/Down), mouse scrolling and text
+selection. `/settings fullscreenExitOutput resume-hint` leaves a resume command
+when exiting; `transcript` prints the conversation. Switching modes preserves
+the editor, history and undo. Scrollbar, wheel speed, copy-on-select, editor
+padding, autocomplete rows, cursor, output padding and double-Escape behavior
+are configurable in `/settings`.
+
+`/settings theme` previews built-in and custom themes from the config directory's
+`themes/`. Escape restores the prior theme. Custom files reload after valid edits;
+`auto` follows terminal light/dark changes and `system` derives Pi's palette from
+terminal color replies. Pi's namespaced action IDs work in `keybindings.json`
+alongside existing xeno names; an empty array disables an action in its own scope.
 
 ## Why this shape
 
@@ -460,7 +570,7 @@ Every path below was checked with `test -f` on this checkout.
 | `store/context-files.ts` | AGENTS.md discovery |
 | **`src/runtime/`** | impure but thin; the only layer allowed npm packages |
 | `runtime/provider.ts` / `openai.ts` | the two wire formats |
-| `runtime/catalog.ts` / `model.ts` | 12 providers, 23 models |
+| `runtime/catalog.ts` / `model-config.ts` / `model-sources.ts` | Pi + Models.dev union, offline overlays and private provider configuration |
 | `runtime/tools.ts` / `history-tools.ts` | confined tools, complete query results and history retrieval |
 | `runtime/benchmark.ts` | actual Session trials, bounded spending and cache diagnostics |
 | `runtime/loop.ts` | orchestration; every judgement delegates to a pure function in core |

package/docs/install.md

@@ -30,8 +30,16 @@ cd xeno
 bun install
 ```
 
-`bun install` pulls the one runtime dependency (`@anthropic-ai/sdk`)
-and the TypeScript dev tooling.
+`bun install` pulls the provider SDK, Pi text layout/Markdown dependencies,
+syntax highlighting, Mermaid, Photon image processing, and TypeScript tooling.
+The exact versions are in `package.json` and `bun.lock`.
+
+Pi native helpers for macOS, Linux X11 and Windows (arm64/x64) ship with the
+package. They are pinned upstream builds with matching source and hashes;
+startup does not download or compile them. Missing platform support uses the
+clipboard command fallbacks. The packaged macOS helper was load-tested on
+this machine; Linux/Windows payloads and routing are checked without claiming
+native device acceptance.
 
 Run the CLI without linking:
 
@@ -55,8 +63,10 @@ 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.
 
-A workspace that already has a session is resumed. `--fresh` starts a
-new session beside it; nothing is deleted.
+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.
 
 ## Credentials
 
@@ -64,7 +74,8 @@ Resolution order, first match wins:
 
 1. `--api-key`
 2. `~/.xeno/auth.json` (created `0600` by `/login`)
-3. the provider's environment variable
+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.
@@ -111,7 +122,8 @@ 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 catalog overlay (written by `xeno models --refresh`)
+models.json       optional user provider/model configuration
+models-cache.json generated catalog cache (written by `xeno models --refresh`)
 keybindings.json  optional
 prompts/ skills/  optional
 ```

package/docs/providers.md

@@ -0,0 +1,147 @@
+# 供应商、模型目录与自定义配置
+
+xeno 内置 Pi 0.99.1 和 OpenCode 所用 Models.dev 的固定源并集：226 个供应商、7,501 个模型条目。同一个模型在不同供应商下分别计数。目录保留能力与已知价格；未提供的价格显示未知，不用零补全。
+
+来源固定为 Pi `1b347794e2a630e4359f2584f4eea388145d0ddf`、OpenCode `2fa3363c924c5c3e367b84a87ae478296a0ed59b`，Models.dev JSON SHA256 `7345de7358c471e78ac756aed556cd804677cd0d8748b71edc3931225440158f`。SDK 固定为 `@earendil-works/pi-ai@0.99.1`；引入它是为了复用维护中的原生协议和签名处理，避免在 xeno 重写十套 SDK。SDK 仅在 runtime；原有 TUI vendor 的版本与升级方式独立。
+
+## 目录和选择
+
+```sh
+xeno --list-models siliconflow
+xeno --provider deepseek --model deepseek-flash
+xeno --model google/gemini-2.5-flash
+xeno models --refresh
+```
+
+按 `provider/model` 识别模型。完整标识优先于其他供应商包含斜杠的原始 ID；裸 ID 多义时给出候选，不按目录顺序猜。旧会话保存了供应商时精确恢复；只存 ID 的旧会话需要目录中的唯一匹配。
+
+目录优先级：内置 → `~/.xeno/models-cache.json` → `~/.xeno/models.json`。启动、列举、选择、恢复和 `/reload` 共用同一解析入口。缓存更新模型元数据时保留原有已验证模型的 wire dialect；用户配置仍可明确覆盖它。刷新成功原子替换缓存，失败保留原缓存，始终不重写用户配置。`XENO_CONFIG_DIR` 可以替换这个目录。启动不联网；`--offline` 禁止显式刷新。
+
+编辑配置后执行 `/reload`。当前模型的端点、API、wire ID 或回放格式变化会记录 checkpoint；纯凭据轮换不切段。禁用当前模型后，下一条输入保留为草稿，需要重新选择模型。供应商错误或配置错误不会使请求转到另一个账户。
+
+新的 assistant 事件同时记录回放配置的摘要，恢复时从日志比较，配置别名不变也能识别上游协议变化。摘要不包含凭据或端点原文。没有摘要的旧原生配置在首次接入时先建立 checkpoint；旧的默认传输保持原恢复行为。
+
+## 本地无认证端点（Pi 分组）
+
+以下内容保存为 `~/.xeno/models.json`；端口、模型 ID 与本地服务保持一致。
+
+```json
+{
+  "providers": {
+    "local": {
+      "api": "openai-completions",
+      "baseUrl": "http://127.0.0.1:1234/v1",
+      "auth": false,
+      "models": [{
+        "id": "my-local-model",
+        "name": "Local model",
+        "contextWindow": 32768,
+        "maxTokens": 4096,
+        "compat": {
+          "supportsStore": false,
+          "supportsDeveloperRole": false,
+          "maxTokensField": "max_tokens"
+        },
+        "samplingParams": { "top_k": 40, "min_p": 0.05 }
+      }]
+    }
+  }
+}
+```
+
+`xeno --model local/my-local-model` 使用该条目。`auth: false` 或 `authHeader: false` 关闭自动认证；SDK 构造所需的内部占位 key 不会发到服务器。`authHeader: "x-custom-key"` 可把最终解析的 key 放进指定头。Google 原生 SDK 拥有认证流程，不支持这两种头替换方式；本地兼容服务使用 OpenAI 接口。
+
+## OpenCode 分组、别名与私有配置
+
+```json
+{
+  "provider": {
+    "company": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "https://gateway.example.com/v1",
+        "apiKey": "{env:COMPANY_API_KEY}",
+        "temperature": 0.2
+      },
+      "headers": { "x-tenant": "${COMPANY_TENANT}" },
+      "models": {
+        "coding": {
+          "id": "upstream-model-id",
+          "limit": { "context": 128000, "output": 8192 },
+          "reasoning": true,
+          "thinkingLevelMap": { "off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": null, "max": null },
+          "compat": { "supportsStore": false, "supportsDeveloperRole": false, "maxTokensField": "max_tokens" },
+          "body": { "top_p": 0.9 }
+        }
+      }
+    }
+  }
+}
+```
+
+选择 `company/coding`，线上请求使用 `upstream-model-id`。`npm` 仅用于识别已接通的协议，不会安装或执行任意供应商包；也可以直接指定 `api`。OpenCode 的完整应用配置、插件、任意 SDK 选项不在这个解析器的兼容范围。
+
+凭据优先级为 CLI `--api-key` → `auth.json` → 模型/供应商 `apiKey` → 供应商环境变量。供应商 `apiKey` 可被模型覆盖；头和 scoped env 按字段合并。指定来源失败就报错，不向下兜底。
+
+`apiKey`、`headers`、`env` 和 `baseUrl` 支持字面字符串、`$VAR` / `${VAR}` / `{env:VAR}`，以及以 `!` 开头的本地命令。命令只有在凭据解析或实际请求需要时执行，不在目录解析时执行。`$$` 和 `$!` 表示字面开头字符。保留 xeno 原有规则：裸 `MY_KEY` 是字面 key，引用变量要写 `$MY_KEY`。只把自己信任的命令写入用户配置；目录缓存不含用户秘密。
+
+`env` 只作用于该供应商，不更改全局进程环境。变量顺序不影响结果，循环引用拒绝。密钥、私有请求头、env 值与请求 options 保存在私有配置中，不随模型对象进入模型列表或日志。
+
+## 覆盖与启停
+
+```json
+{
+  "providers": {
+    "deepseek": {
+      "apiKey": "$DEEPSEEK_API_KEY",
+      "modelOverrides": {
+        "deepseek-flash": { "maxTokens": 8192, "headers": { "x-route": "coding" } }
+      },
+      "allowlist": ["deepseek-*"],
+      "denylist": ["*-deprecated"]
+    }
+  },
+  "disabled_providers": ["unused-provider"]
+}
+```
+
+`modelOverrides` 只修改已有条目；`models` 可以新增。保留旧的 `[{provider,id,api,...}]` 或 `{ "models": [...] }` 扁平格式。支持 provider/model 的 `disabled: true` / `enabled: false`、全局 `enabled_providers` / `disabled_providers`，以及 `allowlist` / `denylist`（同义 `whitelist` / `blacklist`），模式支持 `*` 和 `?`，deny 优先。无效同级模型给出字段路径，有效同级项继续可用；损坏的显式覆盖不会继续使用原来的凭据。
+
+## 原生协议和云认证
+
+| api | 接口与认证 |
+|---|---|
+| `anthropic-messages` | Anthropic、支持 Messages 的网关；API key 或已有 Claude OAuth |
+| `openai-completions` | Chat Completions 兼容端点 |
+| `openai-responses` | OpenAI Responses；每次发完整投影，`store: false` |
+| `openai-codex-responses` | ChatGPT 订阅端点；`/login codex` 或 `OPENAI_CODEX_ACCESS_TOKEN` |
+| `azure-openai-responses` | Azure key + resource/base URL；支持 `AZURE_RESOURCE_NAME` / `AZURE_API_KEY` 别名 |
+| `google-generative-ai` | Gemini 原生 API，Google/Gemini API key |
+| `google-vertex` | Vertex API key，或 `auth: "ambient"` + ADC；项目和位置必需 |
+| `bedrock-converse-stream` | AWS bearer token、profile、IAM/容器/身份链；`auth: "ambient"` 显式使用 SDK 凭据链 |
+| `mistral-conversations` | Pi 的 Mistral 原生适配 |
+| `pi-messages` | Pi Messages 兼容服务器 |
+
+Vertex 可配置 scoped `env`：`GOOGLE_APPLICATION_CREDENTIALS`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_CLOUD_LOCATION`；也接受 OpenCode 的 `GOOGLE_VERTEX_PROJECT` / `GOOGLE_VERTEX_LOCATION`。Bedrock 使用 `AWS_PROFILE`、`AWS_REGION` 等 SDK 环境设置；resource/project/location 不会被当成 API key。需要端点模板的服务必须提供对应变量，例如 Cloudflare 的 account/gateway。
+
+旧 `auth.json` 中存于 `openai` 的 Codex OAuth 可由 `openai-codex` 兼容读取；显式原生条目优先，普通 OpenAI API key 不共享到订阅协议。新的 `/login codex` 写入 `openai-codex`。其他 Pi 专属订阅登录流程不冒充已接入；可按协议配置 key/token。
+
+## 可配置参数与边界
+
+- `compat` / `nativeCompat` 传递 Pi 协议兼容能力；`thinkingLevelMap` 明确本地思考档到上游值的映射。
+- `options` 支持 `temperature`、`samplingParams`、`cacheRetention`、`timeoutMs`、`maxRetryDelayMs`、`metadata`；具体协议只消费自己支持的参数。云 region/profile 通过 `env`。不认识的 option 明确报错。
+- `samplingParams` 用于 OpenAI 兼容协议的采样扩展；`body` / `extraBody` 是实际原生请求体的额外字段。模型、system、消息、工具、stream 与服务端会话字段由投影/适配器负责，不能被这些扩展覆盖。
+- D18 保留 xeno 客户端身份；不会自动带 Pi/Claude Code/Copilot 的产品身份或 attribution 头，也不会插入 Claude Code 的身份提示。订阅服务可能因此拒绝第三方客户端；此处不承诺所有订阅账户可用。
+- Google/Vertex SDK 自行管理 HTTP，不使用自定义 fetch；Bedrock 自行管理 AWS HTTP 与重试，外层不再叠加重试。取消与终止状态仍统一交回 xeno。
+
+## 覆盖、排除与验证依据
+
+`src/runtime/model-data.ts` 同时保存完整来源元数据和 1,373 条排除记录。明确无工具能力或非文本输出的模型不进入 agent 可选目录；还需要专用 SDK 的条目保留排除原因，例如 GitLab、WatsonX、Vertex Anthropic、SAP、Merge Gateway、v0、Qvac。可用兼容服务仍可由用户指定 API/端点接入，不能仅新增一个名字就算支持了专用协议。
+
+除了两份上游源码，Cohere、Venice、AIHubMix 的接入分别核对了 [Cohere compatibility API](https://docs.cohere.com/docs/compatibility-api)、[Venice API 官方资料](https://github.com/veniceai/api-docs/blob/main/agents.md)、[AIHubMix 快速开始](https://docs.aihubmix.com/en/quick-start)。Cohere 的 reasoning effort 按官方能力映射为 none/high；不发送其未支持的 store 字段。
+
+上游配置依据：[Pi models](https://github.com/earendil-works/pi/blob/1b347794e2a630e4359f2584f4eea388145d0ddf/packages/coding-agent/docs/models.md)、[OpenCode provider](https://github.com/anomalyco/opencode/blob/2fa3363c924c5c3e367b84a87ae478296a0ed59b/packages/opencode/src/provider/provider.ts)、[Models.dev](https://models.dev/)。
+
+本地验证覆盖十种协议的真实受控 HTTP（包含 AWS 二进制 EventStream）、签名/工具结果往返、错误重试/取消、实际 CLI JSON 输出、实际 PTY 重载/切换。没有逐一调用付费远程模型，目录条目数量不等于账户可用性或模型质量证明。
+
+重生成时先下载并保存 Models.dev JSON，再运行 `bun scripts/update-model-catalog.ts <snapshot.json>`，审查来源摘要、条目/排除变化及测试固定计数。应用启动不执行生成器。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",
@@ -10,7 +10,9 @@
   "files": [
     "src",
     "README.md",
-    "docs/install.md"
+    "CHANGELOG.md",
+    "docs/install.md",
+    "docs/providers.md"
   ],
   "engines": {
     "bun": ">=1.1.0"
@@ -34,7 +36,11 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.127.0",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@silvia-odwyer/photon-node": "0.3.4",
     "get-east-asian-width": "1.6.0",
+    "grok-mermaid": "0.2.3",
+    "highlight.js": "10.7.3",
     "marked": "18.0.11"
   },
   "publishConfig": {

package/src/apps/cli.ts

@@ -13,25 +13,53 @@
  */
 
 import {
-  parseArgs, startup, readPipedStdin, mergePrintPrompt, silenceTtyEarly,
+  parseArgs, startup, readPipedStdin, mergePrintPrompt, silenceTtyEarly, printCliHelp,
 } from "./startup.ts";
 import { runPrompt, runRepl } from "./shell.ts";
+import { runPackageCommand } from "../runtime/package-manager.ts";
+import { exportHtmlFile } from "./export-cli.ts";
 
-const args = parseArgs(process.argv.slice(2));
+const args = parseArgs(process.argv.slice(2), { deferExtensions: true });
 // Before startup reads auth, scans context files and prints the header:
 // in cooked mode the tty would echo anything typed during that window
 // straight into the banner.
-const restoreTty = silenceTtyEarly({ interactive: !args.print && !args.prompt });
-if (args.print) {
-  // With a prompt already given, stdin is optional context: wait briefly for it.
-  args.prompt = mergePrintPrompt(args.prompt,
-    await readPipedStdin(process.stdin, args.prompt.length > 0 ? { firstByteMs: 3_000 } : {}));
-}
-const app = await startup(args);
-if (args.prompt) {
+const restoreTty = silenceTtyEarly({ interactive: !args.packageCommand && !args.help && !args.version && !args.exportFile && !args.print && !args.prompt });
+process.once("exit", restoreTty);
+try {
+  if (args.help && (args.packageCommand || args.configCommand || args.exportFile || args.version || args.listModels || args.modelsCommand)) {
+    printCliHelp();
+  } else if (args.version) {
+    if (args.extensionArgv) throw new Error("Unknown flags for --version");
+    const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json() as { version: string };
+    console.log(pkg.version);
+  } else if (args.exportFile) {
+    if (args.extensionArgv) throw new Error("Unknown flags for offline export");
+    console.log(`Exported ${await exportHtmlFile(args.exportFile, args.prompt || undefined, args.workspace)}`);
+  } else if (args.packageCommand) {
+    if (args.extensionArgv) throw new Error("Unknown package command flag");
+    if ((args.offline || process.env["XENO_OFFLINE"] === "1") && (args.packageCommand.operation === "update" || args.packageCommand.operation === "install" && args.packageCommand.sources.some(source => /^(npm:|git:|git\+|https?:\/\/|ssh:\/\/|git@)/.test(source)))) throw new Error("--offline prevents remote package installation or updates");
+    const controller = new AbortController(), cancel = () => controller.abort();
+    process.once("SIGINT", cancel); process.once("SIGTERM", cancel);
+    try { await runPackageCommand(args.packageCommand, { workspace: args.workspace, signal: controller.signal, ...(args.approve === undefined ? {} : { trusted: args.approve }) }); }
+    catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = controller.signal.aborted ? 130 : 1; }
+    finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
+  } else {
+    const app = await startup(args);
+    if (args.print) {
+      // With a prompt already given, stdin is optional context: wait briefly for it.
+      args.prompt = mergePrintPrompt(args.prompt,
+        await readPipedStdin(process.stdin, args.prompt.length > 0 ? { firstByteMs: 3_000 } : {}));
+    }
+    if (args.prompt) {
+      restoreTty();
+      await runPrompt(app, args.prompt);
+    } else {
+      await runRepl(app, restoreTty);
+    }
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1;
+} finally {
+  process.off("exit", restoreTty);
   restoreTty();
-  await runPrompt(app, args.prompt);
-} else {
-  try { await runRepl(app); }
-  finally { restoreTty(); }
 }