triss-coworker 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] — 2026-08-05
+
+### Added
+
+- **Coder model management.** `triss coder models` discovers the effective
+  model configuration and live provider catalogue; `triss coder model set`
+  safely switches persistent main/small model pairs with wizard diagnostics,
+  transactional writes, and retained-record rollback recovery.
+
+### Changed
+
+- OpenCode Zen's preferred/offline-fallback pair now starts with
+  `opencode/deepseek-v4-flash-free` instead of the retired
+  `opencode/hy3-free`; the live catalogue remains authoritative. Existing
+  provider/model mismatches produce actionable recovery choices without
+  silently switching providers.
+
+### Fixed
+
+- One-shot `ask` and `review` responses now preserve providers' top-level
+  `final_text` instead of reporting an empty result after a successful call.
+- GLM model switching no longer requires `--allow-unverified` when the provider
+  has no catalogue API; Crush accepts the documented Z.AI aliases, omitted
+  small-model values are preserved, and locks owned by dead processes can be
+  reclaimed safely.
+
 ## [0.26.0] — 2026-07-27
 
 ### Added
@@ -780,7 +806,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of `triss-coworker`.
 
-[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.26.0...HEAD
+[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.27.0...HEAD
+[0.27.0]: https://github.com/ayleen/triss-coworker/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/ayleen/triss-coworker/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/ayleen/triss-coworker/compare/v0.24.2...v0.25.0
 [0.24.2]: https://github.com/ayleen/triss-coworker/compare/v0.24.1...v0.24.2

package/README.md

@@ -271,7 +271,7 @@ and writing**.
 | `triss review`     | Code review on current branch or a PR (diff + linked ticket) | The agent reading the whole diff |
 | `triss commit-msg` | Generates a commit message from staged diff           | Hand-writing or copy-pasting from web LLMs |
 | `triss usage`      | Cumulative cost / token usage with per-project breakdown | Squinting at stderr after each call |
-| `triss coder init` | Sets up a coding agent (default `opencode` engine; `--engine crush` for crush): provider key (Z.AI GLM default; `--provider opencode-zen` for free OpenCode Zen models like `hy3`; `--provider moonshot` for Kimi pay-as-you-go; `--provider kimi-for-coding` for the Kimi subscription), `opencode.json` / crush models + `permissions.run` policy, agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model` | Manually installing/configuring opencode |
+| `triss coder init` | Sets up a coding agent (default `opencode` engine; `--engine crush` for crush): provider key (Z.AI GLM default; `--provider opencode-zen` for free rotating OpenCode Zen models — discover the current id with `triss coder models`; `--provider moonshot` for Kimi pay-as-you-go; `--provider kimi-for-coding` for the Kimi subscription), `opencode.json` / crush models + `permissions.run` policy, agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model` | Manually installing/configuring opencode |
 | `triss coder run` | Spawns the coding agent (GLM, Kimi, or Zen models) and prints one JSON envelope (`--engine opencode\|crush`; `--isolate` for a disposable worktree — opencode defaults to isolate-OFF, crush defaults to isolate-ON; crush adds opt-in `--restrict`/`--no-restrict` for its CLI allowlist). **POSIX only** (macOS/Linux) — refuses to run on Windows. | Manually driving `opencode run` and parsing its ndjson stream |
 | `triss coder clean` | Removes finished `.triss/wt` isolation worktrees (`--all` forces all) | Manually finding and deleting stale git worktrees |
 | `triss init`       | Drops a tiny (~15 line) delegation block into `CLAUDE.md` / `AGENTS.md` | Hand-writing routing rules         |
@@ -464,8 +464,8 @@ triss coder clean                                 # remove finished isolation wo
 ```
 
 `triss coder init` first asks which provider to configure — **Z.AI GLM**
-(default), **OpenCode Zen** (`--provider opencode-zen`, free models incl.
-Hunyuan `hy3`), **Moonshot Kimi** (`--provider moonshot`, pay-as-you-go
+(default), **OpenCode Zen** (`--provider opencode-zen`, free rotating
+models), **Moonshot Kimi** (`--provider moonshot`, pay-as-you-go
 `moonshotai/*` models like `kimi-k2.7-code`), or **Kimi for Coding**
 (`--provider kimi-for-coding`, the flat-rate subscription serving Kimi K3).
 For Z.AI it probes which plan your key works with (subscription vs.
@@ -509,23 +509,17 @@ natively; triss also forwards it as `ZAI_API_KEY` for older binaries; see
 **Providers** — the `opencode` engine isn't limited to Z.AI. The required
 API key follows the model's `<provider>/` prefix: `zai-coding-plan/*` and
 `zai/*` (GLM) use `ZHIPU_API_KEY`; `opencode/*` models — served free by
-[OpenCode Zen](https://opencode.ai/docs/zen/), e.g. **`opencode/hy3-free`**
-(Tencent Hunyuan 3) — use `OPENCODE_API_KEY`; `moonshotai/*` (and the
-China-mainland `moonshotai-cn/*`) Kimi models use `MOONSHOT_API_KEY`; and
-`kimi-for-coding/*` models — the flat-rate
+[OpenCode Zen](https://opencode.ai/docs/zen/) — use `OPENCODE_API_KEY`;
+`moonshotai/*` (and the China-mainland `moonshotai-cn/*`) Kimi models use
+`MOONSHOT_API_KEY`; and `kimi-for-coding/*` models — the flat-rate
 [Kimi for Coding](https://www.kimi.com/code/docs/en/) subscription, e.g.
-**`kimi-for-coding/k3`** (Kimi K3) — use `KIMI_API_KEY`. To point coder at
-a Zen model:
+**`kimi-for-coding/k3`** (Kimi K3) — use `KIMI_API_KEY`. Zen ids rotate
+freely, so discover the current id and pass it rather than hard-coding one:
 
 ```bash
-triss coder init --provider opencode-zen         # guided: key + opencode.json
-# …or by hand:
-triss config set OPENCODE_API_KEY <key>          # or add it to .triss.env
-export TRISS_CODER_MODEL=opencode/hy3-free        # default it for every run
-export TRISS_CODER_SMALL_MODEL=opencode/hy3-free
-triss coder run "add input validation to /signup"
-# …or per-run, without changing the default:
-triss coder run "..." --model opencode/hy3-free
+triss coder init --provider opencode-zen              # guided: key + opencode.json
+triss coder models --provider opencode-zen            # see live Zen ids
+triss coder run "..." --model opencode/<current-id>   # per-run override
 ```
 
 Kimi works the same way:
@@ -539,13 +533,16 @@ triss coder run "..." --model kimi-for-coding/k3
 ```
 
 `triss coder run` passes the resolved model to opencode with `--model` and
-forwards only the key that model needs, so a Zen run works with
-`OPENCODE_API_KEY` alone and a Kimi run with `MOONSHOT_API_KEY` /
-`KIMI_API_KEY` alone — no Z.AI key required. The deny-first `opencode.json`
-bash policy applies to every provider. Any Zen model id works via
-`TRISS_CODER_MODEL=opencode/<id>` / `--model`, not just the free ones the
-picker lists. (The `crush` engine speaks Z.AI only.) Full details, the model
-catalogue, and every configuration path are in
+forwards only the key that model needs — no Z.AI key is required for Zen or
+Kimi runs. A shell-exported `TRISS_CODER_MODEL` is a runtime override of the
+MAIN model only (it sits in the OpenCode-main precedence chain: one-run `--model`
+→ shell `TRISS_CODER_MODEL` → project `.triss.env` → global `.env` → built-in
+default), so it changes the main model for every run until unset.
+`TRISS_CODER_SMALL_MODEL` is setup intent consumed by `triss coder init` /
+`triss coder model` — it does not swap the small model mid-run (opencode reads
+`small_model` from `opencode.json`); use `--model` for a one-run main-model
+override. The deny-first `opencode.json` bash policy applies to every provider.
+Full details, the model catalogue, and every configuration path are in
 [docs/opencode-zen.md](docs/opencode-zen.md).
 
 If your Z.AI plan hits its usage limit, `triss coder run` fails fast with
@@ -555,6 +552,73 @@ opencode retries the throttled call silently, so the reset time is read
 from the engine log and the run is killed within a few seconds of the
 limit.
 
+**Model management — engine vs provider.** Two independent axes; most
+confusion is conflating them:
+
+- **Engine** = *how* the agent is launched: `opencode` (default) or
+  `crush`. Set at `triss coder init --engine …` or per run with
+  `triss coder run --engine …`.
+- **Provider** = *which* API serves the model: Z.AI GLM, OpenCode Zen,
+  Moonshot Kimi, Kimi for Coding. Set at `triss coder init --provider …`.
+
+Not every engine speaks every provider:
+
+| Engine     | Providers served                                  |
+| ---------- | ------------------------------------------------- |
+| `opencode` | Z.AI GLM, OpenCode Zen, Moonshot, Kimi for Coding |
+| `crush`    | Z.AI GLM (coding-plan only)                       |
+
+`triss coder init` drives setup in that order — **engine, then provider,
+then it asks for only that provider's credential** and writes the matching
+model prefix (`opencode/<id>`, `zai-coding-plan/*`, `moonshotai/*`, or
+`kimi-for-coding/*`).
+
+**Choosing a model.** `--model` on `triss coder run` is a
+**single-run override of the main model only** — it does not persist
+and does not change the small/summarization model. To persist a
+choice, use `triss coder model set` — positional main plus `--small` —
+which requires you to name the engine and the scope explicitly:
+
+```bash
+# global, opencode engine: positional main + --small; --yes for noninteractive use
+triss coder model set --engine opencode --global \
+  opencode/<id> --small opencode/<id> --yes
+# local, crush engine: canonical coding-plan GLM pair
+triss coder model set --engine crush --local \
+  zai-coding-plan/glm-5.2 --small zai-coding-plan/glm-5-turbo --yes
+```
+
+**Discovering models.** `triss coder models` lists what the resolved
+engine/provider offers for that invocation, with filters and a
+machine-readable form:
+
+```bash
+triss coder models                          # current effective engine/provider
+triss coder models --engine opencode        # resolved provider for the OpenCode engine
+triss coder models --provider opencode-zen  # just OpenCode Zen
+triss coder models --json                   # for scripting
+```
+
+**When a Zen model goes stale.** Free OpenCode Zen models rotate — no
+specific id is guaranteed to stay (the once-free `opencode/hy3-free`
+Hunyuan model is the canonical stale-model incident). If a model is
+removed upstream, recovery stays **inside Zen**, not a silent jump to
+GLM. See what is live and re-pick explicitly:
+
+```bash
+triss coder models --provider opencode-zen       # current Zen ids
+triss coder model set --engine opencode --global \
+  opencode/<current-id> --small opencode/<current-id> --yes
+```
+
+Triss surfaces that replacement command rather than auto-switching you
+to GLM.
+
+Full flag reference, the model catalogues, key/endpoint routing, and
+the stale-model recovery flow are in [docs/glm-clients.md](docs/glm-clients.md),
+[docs/opencode-zen.md](docs/opencode-zen.md), and
+[docs/configuration.md](docs/configuration.md).
+
 ## Integrations
 
 External-service plugins live under `src/integrations/<name>/`. They are
@@ -636,6 +700,12 @@ triss review --provider kimi                     # pro preset → kimi-k3
 triss ask --paths ... --question "..." --provider kimi --model flash  # kimi-k2.6
 ```
 
+One-shot `ask` / `review` output is provider-shape tolerant: Triss emits the
+assistant text whether the successful response carries OpenAI-style
+`choices[0].message.content` or a top-level `final_text`. A present
+`final_text` must never be treated as an empty response or dropped by the CLI
+or MCP renderer.
+
 For GLM, `pro` maps to `glm-5.2` on both endpoints, while `flash` — the cheap
 bulk-read tier — maps to `glm-4.7` on the subscription endpoint and to
 `glm-4.5-air` ($0.20/$1.10 per 1M) on pay-as-you-go. The subscription endpoint

package/bin/triss.js

@@ -39,6 +39,7 @@ import {
   runUnset,
 } from '../src/commands/config.js';
 import { runCoderInit, runCoderRun, runCoderClean } from '../src/commands/coder.js';
+import { runCoderModels, runCoderModelSet, runCoderModelRollback } from '../src/commands/coder-models.js';
 import { loadIntegrations } from '../src/integrations/_registry.js';
 import { withCall } from '../src/call-context.js';
 
@@ -181,6 +182,8 @@ config
   .option('-f, --force', 're-prompt for keys that are already set')
   .option('--standard', 'API key + one model only — skip the standard/advanced prompt')
   .option('--advanced', 'full wizard with presets, base URL, integrations — skip the prompt')
+  .option('--coder-engine <name>', 'coder target only: coding engine to configure (opencode default, or crush). `coder init` uses --engine')
+  .option('--coder-provider <name>', 'coder target only: opencode engine provider (zai, opencode-zen, moonshot, kimi-for-coding). `coder init` uses --provider')
   .action(wrap(runWizard));
 
 config
@@ -227,7 +230,7 @@ config
 
 const coder = program
   .command('coder')
-  .description('Run a GLM coding agent (opencode or crush engine)');
+  .description('Run a coding agent (OpenCode or Crush engine)');
 
 coder
   .command('init')
@@ -235,7 +238,7 @@ coder
   .option('-g, --global', 'save to the global scope (~/.config/triss/.env, ~/.config/opencode/)')
   .option('-l, --local', 'save to the project scope (./.triss.env, ./opencode.json)')
   .option('--engine <name>', 'coding engine to configure: opencode (default) or crush')
-  .option('--provider <name>', 'opencode engine model provider: zai (Z.AI GLM, default), opencode-zen (free models incl. hy3), moonshot (Kimi pay-as-you-go), or kimi-for-coding (subscription)')
+  .option('--provider <name>', 'opencode engine model provider: zai (Z.AI GLM, default), opencode-zen (free rotating models — discover with `triss coder models`), moonshot (Kimi pay-as-you-go), or kimi-for-coding (subscription)')
   .option('--allow-unsafe-bash', 'proceed even if an existing opencode.json has no deny-first bash policy (the agent runs with --auto)')
   .action(wrap(runCoderInit));
 
@@ -246,7 +249,7 @@ coder
   .option('--session <id>', 'triss-side session slug, mapped to a real opencode session id in .triss/sessions.json')
   .option('--continue', 'continue the most recent opencode session (maps to opencode --continue)')
   .option('--agent <name>', 'opencode agent template to use', 'coder')
-  .option('--model <p/m>', 'override the model for this run only')
+  .option('--model <p/m>', 'override the MAIN model for this one run only (does not change small_model or repair persistent config; use `triss coder model set` for that)')
   .option('--isolate', 'run in a disposable git worktree under .triss/wt/<slug>')
   .option('--no-isolate', 'disable worktree isolation (opencode defaults to OFF; crush defaults to ON)')
   .option('--restrict', 'crush only: enforce the allowlist via CLI --allow-bash/--allow-tool flags (--restrict-run). Opt-in (default OFF)')
@@ -263,6 +266,51 @@ coder
   .option('--all', 'force-remove every worktree under .triss/wt, regardless of diff state')
   .action(wrap(runCoderClean));
 
+coder
+  .command('models')
+  .description('List current + live coder models, provider compatibility, and credential readiness (read-only)\n\n' +
+    'Configuration sources:\n' +
+    '  • opencode: project opencode.json (local) or ~/.config/opencode/opencode.json (global)\n' +
+    '  • crush: ./.crush/crush.json (local) or ~/.local/share/crush/crush.json (global)')
+  .option('--engine <name>', 'coding engine: opencode (default) or crush')
+  .option('--provider <name>', 'provider kind: zai, opencode-zen, moonshot, or kimi-for-coding')
+  .option('--json', 'print the stable machine-readable state object (no secrets)')
+  .action(wrap(runCoderModels));
+
+// `coder model` is a command GROUP whose only leaf today is `set`. Registered
+// as a nested group so `triss coder model set --help` prints its OWN usage line
+// (`Usage: triss coder model set ...`) rather than the parent `coder` usage.
+const coderModel = coder
+  .command('model')
+  .description('Inspect or change persistent coder models (e.g. `triss coder model set`)');
+
+coderModel
+  .command('set [main-model]')
+  .description(
+    'Persistently switch the coder main/small models for one engine+scope (non-interactive; needs --yes to write). ' +
+      'A one-run main override is `triss coder run --model` (main-only, not a persistent repair).\n\n' +
+      'Engines and configuration targets:\n' +
+      '  • opencode: project opencode.json (local) or ~/.config/opencode/opencode.json (global); runtime main follows TRISS_CODER_MODEL env precedence, config main is opencode.json.model\n' +
+      '  • crush: project .crush/crush.json (local) or ~/.local/share/crush/crush.json (global)'
+  )
+  .option('--small <model>', 'small/fast model id (omit to keep the current compatible value)')
+  .option('--engine <name>', 'coding engine: opencode (default) or crush')
+  .option('--provider <name>', 'provider kind: zai, opencode-zen, moonshot, or kimi-for-coding')
+  .option('-g, --global', 'write to the global scope (OpenCode: ~/.config/opencode/opencode.json + global .env; Crush: ~/.local/share/crush/crush.json)')
+  .option('-l, --local', 'write to the project scope (OpenCode: ./opencode.json + ./.triss.env; Crush: ./.crush/crush.json)')
+  .option('--allow-unverified', 'proceed past a not-verified catalogue (timeout/http-error/parse-error) ONLY — never auth or an authoritative unavailable result')
+  .option('--allow-unsafe-bash', 'proceed even if the existing opencode.json lacks the deny-first bash policy')
+  .option('--yes', 'non-interactive confirmation: apply the planned switch (required to write; without it the plan is printed and nothing is changed)')
+  .action((mainModel, opts) => wrap(runCoderModelSet)(mainModel, opts));
+
+coderModel
+  .command('rollback')
+  .description('Restore retained transaction record (opencode.json / crush.json + env pins)')
+  .requiredOption('--from <absolute-record-dir>', 'absolute path to the retained transaction record directory')
+  .option('-g, --global', 'restore to the global scope (~/.config/opencode/ or ~/.local/share/crush/)')
+  .option('-l, --local', 'restore to the project scope (./opencode.json or ./.crush/crush.json)')
+  .action((opts) => wrap(runCoderModelRollback)(opts.from, opts));
+
 function wrap(fn) {
   return async (...args) => {
     try {