@pithosai/pithosai 1.0.7 → 1.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithosai/pithosai",
-  "version": "1.0.7",
+  "version": "1.0.32",
   "description": "Pithos AI CLI — multi-role coding and product agents (bundled distribution).",
   "keywords": [
     "ai",
@@ -14,19 +14,27 @@
   "main": "./dist/pithosai.mjs",
   "bin": {
     "pithosai": "./dist/pithosai.mjs",
-    "pmsai": "./dist/pmsai.mjs",
-    "qasai": "./dist/qasai.mjs",
-    "rdsai": "./dist/rdsai.mjs",
-    "cosai": "./dist/cosai.mjs",
-    "mktai": "./dist/mktai.mjs",
+    "pmsai": "./dist/pmsai",
+    "qasai": "./dist/qasai",
+    "rdsai": "./dist/rdsai",
+    "cosai": "./dist/cosai",
+    "mktai": "./dist/mktai",
     "email-monitor": "./dist/heartbeat.mjs",
-    "wrsai": "./dist/wrsai.mjs",
+    "wrsai": "./dist/wrsai",
     "render-markdown": "./dist/render-markdown.mjs",
-    "init": "./dist/init.mjs"
+    "init": "./dist/init.mjs",
+    "pithosai-git-ai-adapter": "./dist/pithosai-git-ai-adapter.mjs"
   },
   "files": [
     "LICENSE",
+    "CHANGELOG.md",
+    "docs/hooks-usage.md",
+    "docs/KROUTER.md",
+    "src/models/README.md",
+    "src/models/krouter.README.md",
+    "src/agent-orch/READEM.md",
     "dist",
+    "!dist/npc-platform-client",
     "shims",
     "scripts/npm-global-install.js",
     "scripts/postinstall-init.js"
@@ -37,36 +45,54 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.1",
-    "@journeyapps/sqlcipher": "^5.3.1",
-    "@mariozechner/pi-agent-core": "^0.52.5",
-    "@mariozechner/pi-coding-agent": "^0.52.7",
-    "@mariozechner/pi-tui": "^0.52.12",
+    "@earendil-works/pi-agent-core": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@marianmeres/actor": "^1.6.1",
+    "@sinclair/typebox": "^0.34.49",
+    "adm-zip": "^0.5.18",
     "better-sqlite3": "^12.6.2",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
+    "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
+    "cron-parser": "^4.9.0",
     "date-fns": "^4.1.0",
     "handlebars": "^4.7.8",
     "i18next": "^25.8.4",
     "imap": "^0.8.19",
+    "isomorphic-git": "^1.38.6",
+    "json5": "^2.2.3",
     "log4js": "^6.9.1",
+    "lookpath": "^1.2.3",
     "mailparser": "^3.7.1",
     "marked": "^17.0.2",
+    "node-cron": "^3.0.3",
     "nodemailer": "^6.9.16",
+    "ollama": "^0.6.3",
     "pdf-parse": "^1.1.1",
     "playwright": "^1.58.2",
     "proper-lockfile": "^4.1.2",
     "readdirp": "^5.0.0",
-    "uuid": "^13.0.0"
+    "tinyld": "^1.3.4",
+    "uuid": "^14.0.0",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@rspack/cli": "^1.7.6",
     "@rspack/core": "^1.7.6",
+    "dompurify": "^3.3.0",
+    "jsdom": "^27.0.1",
+    "semver": "^7.7.3",
     "vitest": "^4.0.18",
     "webpack-node-externals": "^3.0.0"
   },
+  "optionalDependencies": {
+    "@journeyapps/sqlcipher": "5.3.1"
+  },
   "engines": {
-    "node": ">=18.12.0"
+    "node": ">=22.19.0"
   },
   "publishConfig": {
     "access": "public"

package/src/agent-orch/READEM.md

@@ -0,0 +1,62 @@
+# agent-orch
+
+**Agent orchestration layer** written in shell scripts.
+
+`pithosai.js` supports running agents from shell commands using a predefined `taskId`, `--report-json`, a specific `role`, and the user request. By chaining these roles sequentially, we can orchestrate agents to complete large, complex tasks.
+
+## Usage
+
+```bash
+./run.sh --roles MKT,ARCH,PM,RD --request "Your question here" [--title "Title"] [--lang zh]
+```
+
+### Arguments
+
+| Argument | Required | Description |
+|---|---|---|
+| `--roles` | Yes | Comma-separated list of roles (e.g. `MKT,ARCH,PM,RD,QA,CO,WR,SRE`) |
+| `--request` | Yes* | The user request/question. Can also be passed as the first positional arg. |
+| `--title` | No | Project title (default: `pithosai智能编排服务`) |
+| `--lang` | No | Language code (default: `zh`) |
+
+### Example
+
+```bash
+# Dispatch through MKT → ARCH → PM → RD
+./run.sh --roles MKT,ARCH,PM,RD \
+  --request "分析一下AI智能体平台的市场前景" \
+  --lang zh
+```
+
+## How it works
+
+1. A unique `task_id` is generated for the entire orchestration run.
+2. Each role is dispatched **sequentially** via `role_run()` from `base.sh`.
+3. After a role completes, its report JSON is read and passed as context to the next role.
+4. The final role's report JSON path is printed to stdout.
+
+## API (for shell scripts)
+
+### `dispatch_roles` (in `base.sh`)
+
+```bash
+source "$SCRIPT_DIR/base.sh"
+
+task_id="$(uuidgen)"
+dispatch_roles "$task_id" "$title" "$request" "$lang" MKT ARCH PM RD
+```
+
+Feeds each role sequentially, automatically reading previous role reports as context. Returns the final report JSON path on stdout.
+
+## Role helpers
+
+Each role has a dedicated helper in `base.sh`:
+
+- `mkt_run` — Marketing analysis
+- `arch_run` — Architecture design
+- `rd_run` — Research & Development
+- `pm_run` — Product Management
+- `qa_run` — Quality Assurance
+- `co_run` — Company Operations
+- `wr_run` — Writing
+- `sre_run` — Site Reliability Engineering

package/src/models/README.md

@@ -0,0 +1,469 @@
+# Model configuration (`src/models`)
+
+**Release 1.0.15** — Global OpenRouter models: Anthropic, OpenAI, Google, Meta, Mistral and more are now available via `OPENROUTER_API_KEY`. Refactored `openrouter-reasoning.js` → `enhanceOpenRouterModel()` applies compat (mandatory-thinking, developer-role) to all OpenRouter reasoning models. Legacy `enhanceOpenRouterChinaModel()` alias preserved.
+
+**Release 1.0.14** — TUI full-screen modes, `/shell cd` with history, `/list` project scope, `/model` autocomplete, `/grill-me` plan alignment, `--task-id` for stable task identity.
+
+**Release 1.0.13** — REPL `/model` and `/mode` inspect/switch, script-mode JSON reports (`--report-json`, `--json`), and cron jobs with optional model keys.
+
+**Release 1.0.12** — China-mainland providers (pi-ai direct + OpenRouter), OpenRouter compat patches (`openrouter-reasoning.js`), agent session cache keys tied to resolved models, and Ollama Qwen tool calling.
+
+Pithosai resolves LLM backends through a single map, **`KEY_TO_MODEL`**, and two entry points:
+
+Static catalogs (CLI keys, model ids, China-direct prefixes/env vars, OpenRouter China slugs, default URLs) are seeded from **[`catalog.json`](./catalog.json)**. On first Node run, pithosai copies that file to **`~/.pithosai/models.json5`** (JSON5) if it does not exist, then loads the catalog from the user file. Override the path with `PITHOSAI_MODELS_PATH`. Resolver logic, Cursor CLI streaming, and OpenRouter compat patches stay in JS.
+
+| Function | When used |
+|----------|-----------|
+| `resolveModelConfig(options)` | Default run / agent bootstrap when no explicit `--model` key |
+| `resolveModelConfigByKey(key, KEY_TO_MODEL)` | CLI `--model`, persisted `task.model`, REPL model switch |
+
+Both return `{ model, getApiKey }` where `model` is a [pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai) model object and `getApiKey` supplies the API key at call time.
+
+Project-wide setup examples live in the root [README.md](../../README.md).
+
+---
+
+## How `KEY_TO_MODEL` is built
+
+At module load, keys are merged in this order (later layers override earlier on collision):
+
+1. **OpenRouter (China-mainland slugs)** — from `getModels("openrouter")`, filtered by `openrouter.chinaMainlandSlugs` in the catalog; passes through `enhanceOpenRouterModel()` for compat
+2. **OpenRouter (global slugs)** — from `getModels("openrouter")`, for non-China providers (Anthropic, OpenAI, Google, Meta, Mistral, …) when `OPENROUTER_API_KEY` is set; also passes through `enhanceOpenRouterModel()`. Self-referential `openrouter/` slug models (e.g. `openrouter/auto`) are skipped to avoid duplicating entries from step 1.
+3. **pi-ai direct China providers** — from `getModels(provider)` when the matching API key env is set (`china-pi-ai-providers.js`, metadata from the catalog)
+4. **Hand-crafted entries** — DeepSeek, Ollama, Cursor, Krouter (`deepseek.js`, `ollama.js`, `cursor.js`, `krouter.js`) built from catalog `handCrafted`
+
+Keys are kebab-case, e.g. `qwen-qwen3-235b-a22b-instruct`, `moonshotai-kimi-k2-6`, `deepseek-flash`.
+
+List available keys at runtime:
+
+```bash
+node -e "import { getPublicModelKeys } from './src/models/key-to-model.js'; console.log(getPublicModelKeys().join('\n'))"
+# or: pithosai models   # public keys + discovered krouter composites
+```
+
+(Set the env vars you care about first; the map is built from the current environment.)
+
+### What changed in 1.0.13
+
+| Area | Behavior |
+|------|----------|
+| **`/model` REPL** | No arg or `list` shows the current model label and all available `KEY_TO_MODEL` keys; `/model <key>` switches the session model for subsequent runs (`request-command.js`). |
+| **`/mode` REPL** | No arg shows current run mode; `list` shows `agent`, `dialog`, `plan`; `/mode <mode>` switches mode. Mode affects tool availability with the resolved model (dialog/plan disable shell and write tools). |
+| **`--task-id`** | Main `pithosai` command accepts `--task-id <id>` for a stable task id (default: new UUID per invocation). Combine with `--model` in script runs to resume the same persisted task. |
+| **Script-mode reports** | `--no-interactive --report-json <path>` writes a v1 JSON array after the run; `--json` prints the same to stdout. Each entry includes `taskId`, `role`, `mode`, file change buckets, and exit metadata (not the model key yet — use `--model` explicitly in the command line). Interactive `--report-json` appends one object per agent turn and flushes on `/exit`, `/role`, or `/mode`. |
+| **Cron jobs** | Agent tools `create_cron_task` / `update_cron_task` accept an optional `model` string (a `KEY_TO_MODEL` key). Schedules run via `pithosai cron-daemon`. |
+| **Orchestration scripts** | `src/agent-orch/` shell helpers call `pithosai --no-interactive --report-json` per role with a shared `--task-id` for multi-step agent pipelines. |
+
+### What changed in 1.0.12
+
+| Area | Behavior |
+|------|----------|
+| **China direct APIs** | Catalogs from pi-ai `getModels(provider)` when `KIMI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_*`, `ZAI_API_KEY`, or `XIAOMI_API_KEY` is set (`china-pi-ai-providers.js`). |
+| **OpenRouter (China + Global)** | Slugs filtered in `key-to-model.js` (China‑only and global); entries pass through `enhanceOpenRouterModel()` for mandatory‑thinking and `developer`‑role compat (`openrouter-reasoning.js`). China‑only slugs (Qwen, Baidu, …) disable developer role via `compat.supportsDeveloperRole: false`; Anthropic reasoning models also disable developer role. |
+| **Agent session cache** | `buildAgentSessionCacheKey` uses explicit `--model` keys or `resolved:{provider}:{id}` from `resolveModelConfigForAgentOpts` so env/provider switches invalidate the cached CLI agent (`agent-session.js`). |
+| **Ollama Qwen** | `ollama-qwen25` and `ollama-qwen25-coder` use `supportsTools: true` (full agent tools); `ollama-deepseek-r1` stays chat-only. |
+| **Env helpers** | `provider-env.js` wraps pi-ai `findEnvKeys` / `getEnvApiKey` (trimmed); shared by `config.js` and `key-to-model.js`. |
+
+---
+
+## Provider categories
+
+### 1. DeepSeek (direct API)
+
+| Env | `DEEPSEEK_API_KEY` |
+| Key prefix | `deepseek-*` |
+| Source | Hand-crafted (`deepseek.js`) |
+| API | `https://api.deepseek.com` |
+
+| CLI key | API model id | Notes |
+|---------|--------------|--------|
+| `deepseek-flash`, `deepseek-chat` | `deepseek-v4-flash` | Default chat / daily use |
+| `deepseek-coder`, `deepseek-pro` | `deepseek-v4-pro` | Stronger / coding (`--pro`) |
+| `deepseek-reasoner` | `deepseek-v4-pro` | Thinking enabled (`--reasoner`) |
+
+Env detection uses pi-ai `findEnvKeys` / `getEnvApiKey` via `provider-env.js`.
+
+When `DEEPSEEK_API_KEY` is set, OpenRouter **deepseek** models are omitted from `KEY_TO_MODEL` (direct API is preferred).
+
+---
+
+### 2. China pi-ai direct APIs
+
+Catalog and env var names come from **pi-ai**. Pithosai only adds CLI prefixes and OpenRouter dedupe rules in `china-pi-ai-providers.js`.
+
+| pi-ai provider | Env var(s) | CLI key prefix | Default model (env-only bootstrap) |
+|----------------|------------|----------------|-------------------------------------|
+| `kimi-coding` | `KIMI_API_KEY` | `kimi-*` | `kimi-for-coding` |
+| `moonshotai-cn` | `MOONSHOT_API_KEY` | `moonshotai-cn-*` | `kimi-k2.6` |
+| `moonshotai` | `MOONSHOT_API_KEY` | `moonshotai-*` | `kimi-k2.6` |
+| `zai` | `ZAI_API_KEY` | `z-ai-*` | `glm-4.7` |
+| `minimax-cn` | `MINIMAX_CN_API_KEY` | `minimax-cn-*` | `MiniMax-M2.7` |
+| `minimax` | `MINIMAX_API_KEY` | `minimax-*` | `MiniMax-M2.7` |
+| `xiaomi` | `XIAOMI_API_KEY` | `xiaomi-*` | `mimo-v2.5` |
+
+Example:
+
+```bash
+export MOONSHOT_API_KEY=sk-...
+pithosai request "..." --model moonshotai-kimi-k2-6
+```
+
+When a direct key is set for a provider, the matching **OpenRouter slug** (`moonshotai`, `minimax`, `z-ai`, `xiaomi`, …) is skipped so listings do not duplicate the same models.
+
+**Default env precedence** (first configured wins): Kimi Code → Moonshot CN → Moonshot → Z.ai → MiniMax CN → MiniMax → Xiaomi.
+
+Model ids and endpoints are whatever pi-ai ships for that provider (run `getModels("<provider>")` from `@earendil-works/pi-ai` to inspect).
+
+---
+
+### 3. Local Ollama
+
+| Env | `OPENAI_LOCAL_API_BASE`, `OPENAI_LOCAL_API_KEY` (both required for listing) |
+| Key prefix | `ollama-*` |
+| Source | Hand-crafted (`ollama.js`) |
+| Default base | `http://localhost:11434/v1` |
+
+| CLI key | Ollama model id | Agent tools |
+|---------|-----------------|-------------|
+| `ollama-qwen25` | `qwen2.5:14b` | Yes (`supportsTools: true`) |
+| `ollama-qwen25-coder` | `qwen2.5-coder:14b` | Yes (`supportsTools: true`) |
+| `ollama-deepseek-r1` | `deepseek-r1:14b` | No (chat-only; reasoning model) |
+| `ollama-qwythos-9b-q8` | `qwythos-9b-q8` | Yes (`api: "ollama-native"`) |
+
+Qwen keys appear in `/model` autocomplete when `OPENAI_LOCAL_API_*` is set; `ollama-deepseek-r1` is omitted from autocomplete because tools are disabled.
+
+Use explicit Ollama model keys in `resolveModelConfig` / agent runs, e.g. `model: "ollama-qwen25-coder"` or composite `model: "ollama/qwen2.5-coder:14b"`.
+
+---
+
+### 3b. Krouter (Kiro provider, OpenAI-compatible)
+
+Install the local gateway: [`docs/KROUTER.md`](../../docs/KROUTER.md). Combo + composite guide: [`krouter.README.md`](./krouter.README.md).
+
+| Env | On by default. Optional `KROUTER_API_BASE` (default `http://localhost:20128/v1`); optional `KROUTER_API_KEY`. Opt out with `KROUTER_DISABLED=1`. Legacy `KIRO_*` aliases work. |
+| Key prefix | `krouter-*` (combos) and composite `krouter/<id>` |
+| Source | Catalog combos + lazy `GET /v1/models` metadata (`krouter.js`) |
+| Default base | `http://localhost:20128/v1` |
+| API | `openai-completions` → Krouter `/v1/chat/completions` |
+| Listed combos | `RD`, `ARCH`, `PM`, `QA` |
+| Env-walk default | `RD` (`krouter-rd`); other combos are explicit `--model` only |
+
+| CLI key | Krouter model id |
+|---------|------------------|
+| `krouter-rd` | `RD` |
+| `krouter-arch` | `ARCH` |
+| `krouter-pm` | `PM` |
+| `krouter-qa` | `QA` |
+
+Other gateway ids: `--model krouter/<id>` (alias `kiro/...`), e.g. `krouter/cu/default`. `/model` lists combos only.
+
+```bash
+export KROUTER_API_BASE=http://localhost:20128/v1
+pithosai request "..." --model krouter-rd
+pithosai request "..." --model krouter/cu/default
+```
+
+---
+
+### 4. Cursor CLI
+
+| Env | `CURSOR_MODEL` (required for keys to appear in `KEY_TO_MODEL`) |
+| Key prefix | `cursor-*` |
+| Source | Hand-crafted (`cursor.js`) |
+| API key | None (Cursor CLI auth) |
+
+| CLI key | Typical Cursor model id |
+|---------|-------------------------|
+| `cursor-auto-model` | `auto` |
+| `cursor-sonnet` | `sonnet-4.6` |
+| `cursor-sonnet-thinking` | `sonnet-4.6-thinking` |
+| `cursor-opus` | `opus` |
+| `cursor-gpt` | `gpt` |
+
+Use `--cursor` or `cursor: true` in `resolveModelConfig`; optional string sets an explicit model id.
+
+---
+
+### 5. OpenRouter (China-mainland + Global)
+
+| Env | `OPENROUTER_API_KEY` |
+| Key pattern | `{provider-slug}-{model-id}` (OpenRouter slug + model id, kebab-cased) |
+| Source | `getModels("openrouter")` filtered in `key-to-model.js` |
+
+Keys are built in `key-to-model.js` from each OpenRouter id `provider/model-id`:
+
+1. Drop the `provider/` prefix from the model id.
+2. Join `provider` and the rest with `-`, lowercased, splitting on `-`, `_`, `.`, `/` (colons `:` are kept, e.g. `z-ai-glm-4-5-air:free`).
+
+#### China-mainland slugs
+
+`deepseek`, `qwen`, `moonshotai`, `minimax`, `z-ai`, `xiaomi`, `baidu`, `bytedance-seed`, `stepfun`, `tencent`, `kwaipilot`, `inclusionai`
+
+| OpenRouter slug | CLI key pattern | Example keys (from current pi-ai catalog) |
+|-----------------|-----------------|-------------------------------------------|
+| `deepseek` | `deepseek-{model-id}` | `deepseek-deepseek-v4-flash`, `deepseek-deepseek-v4-pro`, `deepseek-deepseek-chat-v3-0324` |
+| `qwen` | `qwen-{model-id}` | `qwen-qwen-plus`, `qwen-qwen3-235b-a22b`, `qwen-qwen3-vl-235b-a22b-thinking` (reasoning required) |
+| `moonshotai` | `moonshotai-{model-id}` | `moonshotai-kimi-k2-6`, `moonshotai-kimi-k2-5`, `moonshotai-kimi-k2-thinking` |
+| `minimax` | `minimax-{model-id}` | `minimax-minimax-m2-5`, `minimax-minimax-m2-7`, `minimax-minimax-m1` |
+| `z-ai` | `z-ai-{model-id}` | `z-ai-glm-4-7`, `z-ai-glm-4-5`, `z-ai-glm-4-5-air:free`, `z-ai-glm-5-1` |
+| `xiaomi` | `xiaomi-{model-id}` | `xiaomi-mimo-v2-5`, `xiaomi-mimo-v2-flash`, `xiaomi-mimo-v2-5-pro` |
+| `baidu` | `baidu-{model-id}` | `baidu-ernie-4-5-21b-a3b`, `baidu-ernie-4-5-vl-28b-a3b` |
+| `bytedance-seed` | `bytedance-seed-{model-id}` | `bytedance-seed-seed-1-6`, `bytedance-seed-seed-1-6-flash`, `bytedance-seed-seed-2-0-lite` |
+| `stepfun` | `stepfun-{model-id}` | `stepfun-step-3-5-flash`, `stepfun-step-3-7-flash` |
+| `tencent` | `tencent-{model-id}` | `tencent-hy3-preview` |
+| `kwaipilot` | `kwaipilot-{model-id}` | `kwaipilot-kat-coder-pro-v2` |
+| `inclusionai` | `inclusionai-{model-id}` | `inclusionai-ling-2-6-flash`, `inclusionai-ling-2-6-1t`, `inclusionai-ring-2-6-1t` |
+
+#### Global slugs (1.0.15+)
+
+When `OPENROUTER_API_KEY` is set, non-China models are also indexed into `KEY_TO_MODEL`. These use the same `{provider-slug}-{model-id}` pattern:
+
+| OpenRouter slug | CLI key pattern | Example keys |
+|-----------------|-----------------|-------------------------------------------|
+| `anthropic` / `~anthropic` | `anthropic-{model-id}` | `anthropic-claude-sonnet-4`, `anthropic-claude-sonnet-4-6`, `anthropic-claude-opus-4` |
+| `openai` | `openai-{model-id}` | `openai-gpt-4o`, `openai-gpt-4o-mini`, `openai-o3`, `openai-o4-mini` |
+| `google` | `google-{model-id}` | `google-gemini-2-5-flash`, `google-gemini-2-5-pro` |
+| `meta` | `meta-{model-id}` | `meta-llama-4-maverick`, `meta-llama-4-scout` |
+| `mistral` | `mistral-{model-id}` | `mistral-mistral-small-3-1`, `mistral-mistral-large-2411` |
+| `cohere` | `cohere-{model-id}` | `cohere-command-a`, `cohere-command-r-plus` |
+| … | … | Full set changes with the pi-ai OpenRouter catalog. |
+
+The full set depends on the OpenRouter catalog bundled in `@earendil-works/pi-ai` and changes when that package is upgraded. Wildcard usage: `--model qwen-qwen-plus` matches one concrete key, not a pattern.
+
+Slugs listed above are **skipped** when the same provider is already available via a direct pi-ai API key (see section 2). `deepseek` is always skipped when `DEEPSEEK_API_KEY` is set.
+
+Default OpenRouter bootstrap (no `--model` key): `deepseek/deepseek-v4-flash`; `--pro` / `--reasoner` use `deepseek/deepseek-v4-pro`.
+
+**OpenRouter-only China providers** (no pi-ai direct catalog in this repo): e.g. `qwen-*`, `baidu-*`, `stepfun-*`, `tencent-*`, `bytedance-seed-*`, `kwaipilot-*`, `inclusionai-*`.
+
+**OpenRouter-only global providers** (no pi-ai direct catalog in this repo): e.g. `anthropic-*`, `cohere-*`, `ai21-*`, …
+
+**Mandatory-thinking models** — Any OpenRouter model with `reasoning: true` is flagged as mandatory-thinking by `enhanceOpenRouterModel()`. This includes:
+- Models with `thinking` in id or name (e.g. `qwen-qwen3-vl-235b-a22b-thinking`)
+- Hybrid reasoning models (e.g. `anthropic-claude-sonnet-4`) where OpenRouter requires `reasoning` in the request even when effort is optional
+
+pi-ai would otherwise send `reasoning: { effort: "none" }` for thinking-level `off`, which returns HTTP 400 from OpenRouter. Pithosai marks these in `openrouter-reasoning.js`, sets default agent `thinkingLevel` to `medium`, and avoids disabling reasoning on the stream path.
+
+**Developer role:** For China OpenRouter slugs and Anthropic reasoning models, pi-ai would put the system prompt in a `developer` message when `reasoning: true`. These providers reject that role. `enhanceOpenRouterModel()` sets `compat.supportsDeveloperRole: false` on applicable catalog entries; bootstrap applies the same patch and `messages-pi-ai-compat.js` mirrors it for message conversion tests.
+
+**Thinking model examples:**
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+pithosai --no-interactive --model qwen-qwen3-vl-235b-a22b-thinking "Plan the module layout"
+pithosai --no-interactive --model qwen-qwen-plus-2025-07-28:thinking "Summarize this file"
+```
+
+Use `/new` or restart the REPL after switching to a thinking model so the agent bootstraps with default `thinkingLevel: medium`.
+
+#### Example CLI commands
+
+Set OpenRouter and avoid higher-priority providers if you want routing to stay on OpenRouter (unset `DEEPSEEK_API_KEY`, `KIMI_API_KEY`, etc.):
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+Default agent run (no `--model`; uses OpenRouter DeepSeek V4 Flash when no other provider env is set):
+
+```bash
+pithosai --no-interactive "Summarize this repo"
+pithosai --no-interactive --pro "Refactor the auth module"
+pithosai --no-interactive --reasoner "Design a migration plan"
+```
+
+Pick an explicit OpenRouter-backed key with `--model` (value must match a key from `KEY_TO_MODEL`):
+
+```bash
+# Qwen (OpenRouter slug qwen)
+pithosai --no-interactive --model qwen-qwen-plus "Explain this function"
+pithosai task --file ./tasks.md --model qwen-qwen3-235b-a22b-2507
+
+# Baidu ERNIE
+pithosai --no-interactive --model baidu-ernie-4-5-21b-a3b "Draft API docs"
+
+# StepFun
+pithosai --no-interactive --model stepfun-step-3-5-flash "Quick code review"
+
+# ByteDance Seed
+pithosai --no-interactive --model bytedance-seed-seed-1-6 "Plan the feature"
+
+# InclusionAI / Kwaipilot / Tencent (examples; ids vary with OpenRouter catalog)
+pithosai --no-interactive --model inclusionai-ling-2-6-flash "Triage these bugs"
+pithosai --no-interactive --model kwaipilot-kat-coder-pro-v2 "Implement the handler"
+pithosai --no-interactive --model tencent-hy3-preview "Summarize the spec"
+```
+
+In an interactive session, switch model without restarting:
+
+```text
+/model qwen-qwen-plus
+```
+
+List keys available in your current environment (after exporting `OPENROUTER_API_KEY`):
+
+```bash
+node -e "import { getPublicModelKeys } from './src/models/key-to-model.js'; getPublicModelKeys().filter(k => k.startsWith('qwen-')).slice(0,10).forEach(console.log)"
+```
+
+Note: if `MOONSHOT_API_KEY`, `ZAI_API_KEY`, or similar direct keys are set, overlapping `moonshotai-*`, `z-ai-*`, `minimax-*`, and `xiaomi-*` OpenRouter entries are omitted from `KEY_TO_MODEL`; use the direct APIs in [section 2](#2-china-pi-ai-direct-apis) or unset those env vars to use OpenRouter for those families.
+
+---
+
+## REPL `/model` and `/mode`
+
+In an interactive session, inspect or switch the active model and run mode without restarting:
+
+```text
+/model              # current label + available keys + usage
+/model list         # same as /model with no arg
+/model qwen-qwen-plus
+/mode               # current mode + usage
+/mode list          # current mode + agent, dialog, plan
+/mode plan
+```
+
+**Current model label** (`resolveCurrentModelLabel`): explicit `runOpts.model` (a `KEY_TO_MODEL` key) when set; otherwise fallbacks such as `deepseek-reasoner` (`--reasoner`), `deepseek-coder` (`--pro`), `cursor:<id>` (`--cursor`), or `deepseek-chat`.
+
+**Run modes** (`agent`, `dialog`, `plan`) change which tools the agent may call with the resolved model — not the model itself. Autocomplete excludes the current model key and current mode from suggestions (`repl-completer.js`).
+
+After `/model` to a different provider or a mandatory-thinking OpenRouter key, use `/new` or restart so the agent bootstraps with the correct defaults (see [Thinking model examples (1.0.12)](#thinking-model-examples-1012) above).
+
+---
+
+## Script mode (automation)
+
+Use `--no-interactive` with an explicit model key and optional stable task id:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# One-shot run + file report (exit 0 = success, 1 = failure, 2 = stopped)
+pithosai --no-interactive \
+  --model qwen-qwen-plus \
+  --task-id my-feature-spec \
+  --report-json ./runs/spec.json \
+  "Draft the API spec"
+
+# JSON on stdout (banner and agent output suppressed)
+pithosai --no-interactive --json --model moonshotai-kimi-k2-6 "Summarize README"
+```
+
+Report objects include `taskId`, `role`, `mode`, `files`, and timing — useful for shell orchestration (`src/agent-orch/base.sh` passes `--task-id` and `--report-json` across role steps). Cron-created jobs may also set `model` to any key from `getPublicModelKeys()`.
+
+---
+
+## Interactive agent session cache
+
+When `agentSessionRef` is set (interactive CLI), `resolveAgentForRun` reuses one bootstrapped agent until `/new` or the cache key changes. The key includes task id, role, mode, and a model segment from `buildModelCacheSegmentForAgentSession()`:
+
+- Explicit `opts.model` → the KEY_TO_MODEL string (e.g. `qwen-qwen-plus`)
+- Otherwise → `resolved:{provider}:{id}` from `resolveModelConfigForAgentOpts` (e.g. `resolved:kimi-coding:kimi-for-coding`)
+- If nothing resolves → legacy flags (`__reasoner__`, `__pro__`, `__default__`, …)
+
+This prevents reusing a DeepSeek agent after switching env to `KIMI_API_KEY` only, or after `/model` to another provider.
+
+---
+
+## Default resolution order (`resolveModelConfig`)
+
+When no explicit model key is passed:
+
+1. `options.cursor` — Cursor CLI  
+2. `options.local` — explicit Ollama option  
+3. `DEEPSEEK_API_KEY` — DeepSeek V4 (flash / pro / reasoner from flags)  
+4. China pi-ai direct env keys — see section 2 precedence  
+5. `OPENAI_LOCAL_API_*` — Ollama via env  
+6. Krouter — on by default (default `http://localhost:20128/v1`); opt out with `KROUTER_DISABLED` / `KIRO_DISABLED`  
+7. `OPENROUTER_API_KEY` — OpenRouter DeepSeek V4 slugs  
+
+---
+
+## Key routing (`resolveModelConfigByKey`)
+
+| Key prefix / model | API key source |
+|--------------------|----------------|
+| `cursor-*` | Placeholder (`cursor-cli-no-key`) |
+| `deepseek-*` | `getPiAiEnvApiKey("deepseek")` |
+| China direct (`model.provider` in `CHINA_DIRECT_PROVIDER_META`) | `getPiAiEnvApiKey(model.provider)` |
+| `ollama-*` | `OPENAI_LOCAL_API_KEY` + `OPENAI_LOCAL_API_BASE` on model |
+| `krouter-*` | Optional `KROUTER_API_KEY` (default dummy `krouter`); `KROUTER_API_BASE` on model |
+| Other keys in `KEY_TO_MODEL` | `OPENROUTER_API_KEY` |
+
+#### China-mainland model environment variables
+
+Env var names follow [pi-ai `getEnvApiKey`](https://www.npmjs.com/package/@earendil-works/pi-ai) / `findEnvKeys` where applicable. Values must be non-empty after trim.
+
+| Environment variable | Used for | CLI key prefix(es) | Notes |
+|----------------------|----------|-------------------|--------|
+| `DEEPSEEK_API_KEY` | DeepSeek direct API | `deepseek-*` | Also gates hand-crafted DeepSeek keys; skips OpenRouter `deepseek-*` when set |
+| `KIMI_API_KEY` | Kimi Code (`kimi-coding`) | `kimi-*` | e.g. `kimi-for-coding` |
+| `MOONSHOT_API_KEY` | Moonshot intl + CN (`moonshotai`, `moonshotai-cn`) | `moonshotai-*`, `moonshotai-cn-*` | Same env var for both pi-ai providers |
+| `MINIMAX_API_KEY` | MiniMax international (`minimax`) | `minimax-*` | Skips OpenRouter `minimax-*` when set |
+| `MINIMAX_CN_API_KEY` | MiniMax China (`minimax-cn`) | `minimax-cn-*` | China endpoint via pi-ai |
+| `ZAI_API_KEY` | Z.ai / GLM (`zai`) | `z-ai-*` | Skips OpenRouter `z-ai-*` when set |
+| `XIAOMI_API_KEY` | Xiaomi MiMo (`xiaomi`) | `xiaomi-*` | Skips OpenRouter `xiaomi-*` when set |
+| `OPENROUTER_API_KEY` | OpenRouter proxy | China: `qwen-*`, `baidu-*`, `stepfun-*`, `tencent-*`, `bytedance-seed-*`, `kwaipilot-*`, `inclusionai-*`, and any slug not skipped by a direct key. Global (1.0.15+): `anthropic-*`, `openai-*`, `google-*`, `meta-*`, `mistral-*`, `cohere-*`, … | Required for all OpenRouter-backed keys; also used when no direct key is set for `deepseek`, `moonshotai`, `minimax`, `z-ai`, `xiaomi` |
+
+Minimal setup examples:
+
+```bash
+# Direct DeepSeek only
+export DEEPSEEK_API_KEY=sk-...
+
+# Direct Kimi Code only
+export KIMI_API_KEY=sk-...
+
+# OpenRouter for Qwen / Baidu / etc. (unset direct keys for overlapping families)
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# Moonshot CN + international catalogs (both listed when this is set)
+export MOONSHOT_API_KEY=sk-...
+```
+
+pi-ai also defines `XIAOMI_TOKEN_PLAN_CN_API_KEY`, `XIAOMI_TOKEN_PLAN_AMS_API_KEY`, and `XIAOMI_TOKEN_PLAN_SGP_API_KEY` for other Xiaomi providers; pithosai’s China direct catalog currently wires **`XIAOMI_API_KEY`** → `xiaomi` only.
+
+---
+
+## Module map
+
+| File | Role |
+|------|------|
+| `catalog.json` | Bundled seed catalog: slugs, China-direct metadata, defaults, hand-crafted models. Copied to `~/.pithosai/models.json5` on first run |
+| `~/.pithosai/models.json5` | Runtime catalog (JSON5). Edit this file to add or change models without rebuilding pithosai. Override path with `PITHOSAI_MODELS_PATH` |
+| `catalog.js` | Loads/freezes the catalog from `models.json5` (seeded from `catalog.json`); CLI-key and id lookup; listed KEY_TO_MODEL key maps |
+| `user-catalog-file.js` | Resolves `~/.pithosai/models.json5`, seeds JSON5 from bundled JSON, parses JSON5 |
+| `key-to-model.js` | Builds `KEY_TO_MODEL`, `getPublicModelKeys()` |
+| `config.js` | `resolveModelConfig*`, bootstrap flag helpers |
+| `provider-env.js` | pi-ai `findEnvKeys` / `getEnvApiKey` wrappers, `has*` helpers |
+| `china-pi-ai-providers.js` | Direct China catalogs, CLI prefixes, OpenRouter skip set |
+| `openrouter-reasoning.js` | OpenRouter compat for all models: `supportsDeveloperRole: false` (China slugs + Anthropic), mandatory-thinking `thinkingLevelMap` / default `thinkingLevel`, and `isMandatoryOpenRouterReasoningModel` helper |
+| `deepseek.js` | DeepSeek V4 hand-crafted models |
+| `ollama.js` | Local Ollama hand-crafted models |
+| `cursor.js` | Cursor CLI models + `registerCursorProvider()` |
+| `krouter.js` | Krouter combos + `/v1/models` fetch helpers |
+| `index.js` | Public re-exports for the rest of the app |
+
+---
+
+## Tests
+
+```bash
+npm test -- src/models/
+```
+
+Coverage includes `catalog`, `config`, `key-to-model`, `china-pi-ai-providers`, `provider-env`, `openrouter-reasoning`, `ollama`, and the other hand-crafted provider modules.
+
+### Add a model from catalog only
+
+Edit **`~/.pithosai/models.json5`** (created from [`catalog.json`](./catalog.json) on first run). No JS changes are required for listing or `--model` lookup. To change the seed that new installs copy, edit [`catalog.json`](./catalog.json).
+
+| What to add | Where in `catalog.json` |
+|-------------|-------------------------|
+| OpenRouter China slug (Qwen, Baidu, …) | `openrouter.chinaMainlandSlugs` — global OpenRouter models already appear from pi-ai when `OPENROUTER_API_KEY` is set |
+| Direct China / DeepSeek provider | One object in `chinaDirectProviders` (`id`, `envVar`, `keyPrefix`, `openRouterProvider`, `defaultModelId`). Env-walk order is this array’s order. |
+| Krouter combo | One object in `handCrafted.krouter.combos` (`id`, `name`). CLI key is derived (`RD` → `krouter-rd`). Other gateway ids use composite `krouter/<id>`. |
+| Krouter combo | One object in `handCrafted.krouter.combos` with `id` (dashboard combo name, e.g. `RD`) and `name`. CLI key is derived (`RD` → `krouter-rd`). Do not prefix combos with `kr/` — that prefix is for Kiro provider models. Fallback order lives in the kRouter dashboard, not the catalog. Combos are a single CLI key; they are not expanded into `-agentic` / `-thinking` variants. |
+| Ollama / Cursor / DeepSeek hand-crafted model | One object in `handCrafted.ollama` / `cursor` / `deepseek` `models` with `cliKeys`, `id`, `name` |
+
+Keep routing and Cursor CLI streaming in JS. Named `export const …Model` wrappers are optional compatibility aliases, not required to list a new key.