nicoechaniz · Pablomonte · Apr 22, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 18, 2026
diff --git a/.env.example b/.env.example
@@ -75,12 +75,12 @@
 # =============================================================================
 # MiniMax provides access to MiniMax models (global endpoint)
 # Get your key at: https://www.minimax.io
-# MINIMAX_API_KEY=
-# MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL
+# MINIMAX_API_KEY=***
+# MINIMAX_BASE_URL=https://api.minimax.io/anthropic  # Anthropic-compatible endpoint (required for prompt caching)
 
 # MiniMax China endpoint (for users in mainland China)
-# MINIMAX_CN_API_KEY=
-# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL
+# MINIMAX_CN_API_KEY=***
+# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/anthropic  # Anthropic-compatible endpoint (required for prompt caching)
 
 # =============================================================================
 # LLM PROVIDER (OpenCode Zen)

diff --git a/.gitignore b/.gitignore
@@ -70,3 +70,7 @@ mini-swe-agent/
 result
 website/static/api/skills-index.json
 models-dev-upstream/
+
+# Local project memory and session artifacts (never commit)
+.codex
+hermes_conversation_*.json
diff --git a/AGENTS.md b/AGENTS.md
@@ -13,6 +13,17 @@ source .venv/bin/activate   # or: source venv/bin/activate
 `$HOME/.hermes/hermes-agent/venv` (for worktrees that share a venv with the
 main checkout).
 
+## Fork Branch Workflow
+
+This fork uses a two-layer branch model. See `FORK_WORKFLOW.md` for the full procedure.
+
+- `nousmain` is the local mirror of `upstream/main`. Do not commit directly to it.
+- `main` is the integration branch deployed to `~/.hermes/hermes-agent`.
+- Canonical feature/fix branches should be clean patch stacks over `nousmain`, not over `main`.
+- Active canonical branches are documented in `FORK_WORKFLOW.md`.
+- Before push/pull, run `git remote -v` and verify `origin` vs `upstream`.
+- After meaningful fork sync/deploy, also run the CompAII rebirth sync (`python ~/Projects/compaii-state/sync.py`).
+
 ## Project Structure
 
 File counts shift constantly — don't treat the tree below as exhaustive.

diff --git a/AGENTS_SETUP.md b/AGENTS_SETUP.md
@@ -0,0 +1,102 @@
+# Agent Setup Guide
+
+How to set up and run the multi-agent Kanban coding roster on your machine.
+
+## Prerequisites
+
+- Hermes Agent installed and working (`hermes chat -q "hello"`)
+- API keys for your preferred providers in `~/.hermes/.env`
+- Git access to this repo
+
+## Quick Start
+
+```bash
+# 1. Pull latest
+cd ~/Projects/hermes-agent
+git pull origin main
+
+# 2. Sync deploy target (if using gateway)
+cd ~/.hermes/hermes-agent
+git pull local-project main
+
+# 3. Create profiles (one-time)
+hermes profile create riqui
+hermes profile create miki
+hermes profile create maxi
+
+# 4. Copy configs from repo
+cp ~/Projects/hermes-agent/profiles/riqui/config.yaml ~/.hermes/profiles/riqui/
+cp ~/Projects/hermes-agent/profiles/miki/config.yaml ~/.hermes/profiles/miki/
+cp ~/Projects/hermes-agent/profiles/maxi/config.yaml ~/.hermes/profiles/maxi/
+
+# 5. ADAPT PROVIDERS TO YOUR STACK (IMPORTANT)
+# Edit each profile's config.yaml:
+#   - model.provider: your provider (openrouter, anthropic, nous, etc.)
+#   - model.default: your model name
+#   - model.base_url: your provider's endpoint (if needed)
+#   - model.api_key or symlink .env
+$EDITOR ~/.hermes/profiles/riqui/config.yaml
+$EDITOR ~/.hermes/profiles/miki/config.yaml
+$EDITOR ~/.hermes/profiles/maxi/config.yaml
+
+# 6. Copy SOUL.md files
+cp ~/Projects/hermes-agent/profiles/riqui/SOUL.md ~/.hermes/profiles/riqui/
+cp ~/Projects/hermes-agent/profiles/miki/SOUL.md ~/.hermes/profiles/miki/
+cp ~/Projects/hermes-agent/profiles/maxi/SOUL.md ~/.hermes/profiles/maxi/
+
+# 7. Symlink .env and agent-memory
+ln -sf ~/.hermes/.env ~/.hermes/profiles/riqui/.env
+ln -sf ~/.hermes/.env ~/.hermes/profiles/miki/.env
+ln -sf ~/.hermes/.env ~/.hermes/profiles/maxi/.env
+ln -sf ~/.hermes/agent-memory ~/.hermes/profiles/riqui/agent-memory
+ln -sf ~/.hermes/agent-memory ~/.hermes/profiles/miki/agent-memory
+ln -sf ~/.hermes/agent-memory ~/.hermes/profiles/maxi/agent-memory
+
+# 8. Test each profile
+hermes -p riqui chat -q "hello" --quiet
+hermes -p miki chat -q "hello" --quiet
+hermes -p maxi chat -q "hello" --quiet   # ⚠ known issue: maxi needs api_mode fix
+```
+
+## Profile Reference
+
+| Profile | Purpose | Key config | Status |
+|---------|---------|-----------|--------|
+| riqui | Fast surgical coding | max_turns=30, reasoning=minimal | ✓ Working |
+| miki | Deep-thinking coding (Kimi) | max_turns=30, reasoning=high | ✓ Working |
+| maxi | Deep-thinking coding (MiniMax) | max_turns=30, reasoning=high, Anthropic endpoint | ⚠ API mode bug |
+
+## Provider Adaptation
+
+The profiles assume our stack (DeepSeek, Kimi OAuth, MiniMax API key). To use different providers:
+
+### Using OpenRouter
+```yaml
+model:
+  default: openai/gpt-5.4  # or anthropic/claude-sonnet-4-6, etc.
+  provider: openrouter
+```
+
+### Using Anthropic Direct
+```yaml
+model:
+  default: claude-sonnet-4-6-20250514
+  provider: anthropic
+```
+
+### Using Nous Portal
+```yaml
+model:
+  default: anthropic/claude-sonnet-4-6
+  provider: nous
+```
+
+The `agent.max_turns` and `agent.reasoning_effort` settings are provider-agnostic.
+
+## Kanban Worker Rules (CRITICAL)
+
+- All coding profiles MUST have `max_turns >= 25` and `reasoning_effort >= minimal`
+- Lower values cause protocol violations (exhausted iterations before kanban_complete)
+- Kanban dispatcher spawns `hermes -p <profile> --skills kanban-worker chat -q "work kanban task <id>"`
+- Workers MUST end with `kanban_complete()` or `kanban_block()` — text-only exit is a violation
+- Dispatcher auto-blocks after 1 protocol violation (effective_limit=1)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,101 @@
+# Changelog — nicoechaniz/hermes-agent fork
+
+Team-facing summary of changes to our fork. For branch topology and sync commands, see `FORK_WORKFLOW.md`.
+
+> Provider note: profile configs reference DeepSeek, Kimi, and MiniMax providers because that is our stack. Team members using different providers should adapt `model.provider`, `model.default`, and `model.base_url` in each profile's `config.yaml`. API keys go in each profile's `.env` or a symlinked shared `.env`.
+
+## 2026-05-14 — Kimi OAuth architecture consolidation
+
+### Centralized resolution
+
+- `resolve_api_key_provider_credentials()` now automatically tries Kimi CLI OAuth (`~/.kimi/credentials/kimi-code.json`) when no `KIMI_API_KEY` env var is present.
+- Removed 33 lines of scattered ad-hoc OAuth fallback code from `runtime_provider.py` (`_try_kimi_oauth_credentials()` and both call sites).
+- All consumers of the canonical resolver (runtime provider, auxiliary client, etc.) get OAuth automatically without manual fallback code.
+
+### Branch sync
+
+- Cherry-picked missing Kimi commits from `main` into `feat/kimi`:
+  - `_try_refresh_kimi_client_credentials()` in `run_agent.py` (mid-conversation 401 refresh)
+  - `kimi_coding_default_headers()` applied consistently across all provider paths
+- `feat/kimi` is now a complete clean patch stack with no Kimi gaps vs `main`.
+- Merged back to `main`, resolved one minor merge conflict in `agent/auxiliary_client.py`.
+
+### Test fixes
+
+- Fixed `test_resolve_kimi_prefers_cli_oauth_without_api_key`: mock now accepts `**kwargs` to match the new `allow_api_key_fallback=False` call signature.
+- Fixed two pre-existing broken tests with mismatched mock values:
+  - `test_resolve_runtime_provider_kimi_uses_oauth_chat_mode`
+  - `test_resolve_runtime_provider_lmstudio_uses_token_when_present`
+
+### Verification
+
+- All 287 provider/auth tests pass: `scripts/run_tests.sh tests/hermes_cli/test_runtime_provider_resolution.py tests/hermes_cli/test_api_key_providers.py -q`
+
+## 2026-05-13 — Kimi branch consolidation
+
+### Branch workflow
+
+- Canonical Kimi branch is now `feat/kimi`.
+- `feat/kimi` is a clean patch stack over `nousmain`.
+- Superseded branches removed from `origin`:
+  - `feat/kimi-oauth-clean`
+  - `feat/kimi-oauth-clean-v3`
+  - `fix/kimi-context-length-resolution`
+- `main` is the integration branch: `nousmain` plus all active canonical feature branches.
+- Runtime deploy target `~/.hermes/hermes-agent` tracks `origin/main`.
+
+### Kimi support in `feat/kimi`
+
+- Kimi CLI OAuth credentials are read from `~/.kimi/credentials/kimi-code.json` when `KIMI_API_KEY` is not set.
+- `KIMI_API_KEY` takes precedence over OAuth credentials when present.
+- `kimi-coding` supports both endpoints:
+  - `https://api.kimi.com/coding` via Anthropic Messages
+  - `https://api.kimi.com/coding/v1` via OpenAI Chat Completions
+- Kimi CLI-compatible `X-Msh-*` headers and user-agent are applied to Kimi requests.
+- Runtime provider resolution falls back to Kimi OAuth instead of silently producing `no-key-required`.
+- Auxiliary Kimi calls refresh OAuth credentials on 401.
+- Kimi K2.x context lengths are pinned to 262144 where needed and stale OpenRouter underreports are ignored for known providers.
+
+### Verification
+
+- Focused tests: `scripts/run_tests.sh tests/hermes_cli/test_runtime_provider_resolution.py tests/agent/test_model_metadata.py -q --tb=short`
+- Kimi OAuth smoke: `hermes chat --provider kimi-coding -m kimi-k2.6 -q 'Say OK only.' -Q --yolo`
+
+## 2026-05-11 — Kimi K2.6 context window bug
+
+### Problem
+
+Hermes rejected `kimi-k2.6` with a 32768-token context window even though the real context is 262144.
+
+### Root cause
+
+1. Provider mapping was incomplete for `kimi` / `moonshot` aliases.
+2. Provider-unaware OpenRouter metadata could be consulted before curated Hermes defaults.
+
+### Fix
+
+- Added Kimi aliases to models.dev provider mapping.
+- Added explicit Kimi K2.x context-length defaults.
+- Kept provider-specific/curated context data ahead of provider-unaware OpenRouter fallback.
+
+## 2026-05-09 — Multi-agent coding roster and Kanban hardening
+
+### Profiles
+
+- `riqui`: DeepSeek v4-flash, surgical Kanban worker.
+- `miki`: Kimi K2.6 via `kimi-coding` OAuth.
+- `maxi`: MiniMax provider, Anthropic Messages endpoint.
+- `compaii`: architecture/research profile.
+
+### Kanban fixes
+
+- Kanban worker tasks require explicit `toolsets` in task specs.
+- `kanban review create` flow validated end-to-end.
+- Auto-specify triage was added for malformed task specs.
+- Dispatcher self-spawn risk remains important: tasks assigned to the gateway's own profile must stay in `todo`/`triage` until intentionally claimed.
+
+## 2026-05-08 — Upstream sync v2026.5.7
+
+- Rebased fork work onto upstream main at the time.
+- Preserved local fork features.
+- Split gateway service handling between CompAII and profile-specific gateway instances.
diff --git a/FORK_WORKFLOW.md b/FORK_WORKFLOW.md
@@ -0,0 +1,110 @@
+# Fork Workflow — nicoechaniz/hermes-agent
+
+This repository is Nicolás' Hermes Agent fork. It intentionally carries local features that may or may not be upstreamed. Keep this file current whenever the branch topology changes.
+
+## Branch roles
+
+| Branch | Role | Rules |
+|--------|------|-------|
+| `upstream/main` | NousResearch upstream | Read-only reference. Fetch from `https://github.com/NousResearch/hermes-agent.git`. |
+| `nousmain` | Local mirror of upstream main | Must match `upstream/main` exactly after each upstream sync. Do not commit directly. |
+| `main` | Integration branch for our runtime | Merge `nousmain` plus all active canonical feature branches. This is what gets deployed to `~/.hermes/hermes-agent`. |
+| `feat/*` / `fix/*` | Canonical fork features/fixes | Branch from `nousmain`, not from `main`, unless explicitly creating a short-lived integration/docs cleanup branch. Each branch must apply cleanly over `nousmain`. |
+| `backup/*` / `*-legacy` | Safety archives | Do not merge. Keep only while useful for recovery. |
+
+## Current canonical feature branches
+
+These are the active branches we intentionally preserve as separable patches over `nousmain`:
+
+| Branch | Purpose | Notes |
+|--------|---------|-------|
+| `feat/kimi` | Kimi support and corrections | Kimi CLI OAuth from `~/.kimi/credentials/kimi-code.json`; `X-Msh-*` headers; runtime credential resolution; Kimi OAuth refresh on auxiliary 401; Kimi K2.x context-length fixes. This replaces the old `feat/kimi-oauth-clean*` and `fix/kimi-context-length-resolution` branches. |
+| `feat/daemoncraft` | DaemonCraft gateway / embodied-agent integration | Canonical DaemonCraft patch set. Keep clean over `nousmain`; old messy history lives only in `feat/daemoncraft-legacy` / backups. |
+| `feat/minimax-defaults` | MiniMax defaults | Provider defaults for MiniMax Anthropic Messages transport and base URL behavior. |
+| `feat/kanban-review` | Kanban review orchestration | Review graph/templates/CLI wiring for `hermes kanban review`. |
+| `feat/altermundi-cli` | CLI input / interrupt behavior | Ctrl+C priority, interrupt transcript safety, multimodal requeue, TUI config support. |
+| `feat/altermundi-tui` | TUI history behavior | History navigation behavior in the Ink TUI. |
+
+If a branch is superseded, delete the remote branch after the replacement is merged and verified. Leave a local `backup/*` branch only when recent recovery is useful.
+
+## Sync workflow
+
+Before any push or pull, verify remotes:
+
+```bash
+git remote -v
+```
+
+Update the upstream mirror:
+
+```bash
+git fetch upstream main
+git checkout nousmain
+git reset --hard upstream/main
+```
+
+Rebuild each canonical feature branch on top of the new `nousmain`:
+
+```bash
+git checkout feat/kimi
+git rebase nousmain
+# resolve conflicts, run focused tests, then push:
+git push origin feat/kimi --force-with-lease
+```
+
+Repeat for each active canonical branch. Do not rebase `main` onto feature branches; `main` is rebuilt by merging branches.
+
+Rebuild integration `main`:
+
+```bash
+git checkout main
+git reset --hard nousmain
+git merge --no-ff feat/kimi
+git merge --no-ff feat/daemoncraft
+git merge --no-ff feat/minimax-defaults
+git merge --no-ff feat/kanban-review
+git merge --no-ff feat/altermundi-cli
+git merge --no-ff feat/altermundi-tui
+```
+
+Run tests before pushing. Use the wrapper, never raw `pytest`:
+
+```bash
+scripts/run_tests.sh
+```
+
+For provider-specific fixes, add an end-to-end smoke test when credentials are available. Example for Kimi OAuth:
+
+```bash
+hermes chat --provider kimi-coding -m kimi-k2.6 -q 'Say OK only.' -Q --yolo
+```
+
+Push and deploy:
+
+```bash
+git push origin main
+git -C ~/.hermes/hermes-agent fetch origin main
+git -C ~/.hermes/hermes-agent reset --hard origin/main
+```
+
+If the gateway is running and the change affects gateway/runtime behavior, restart the relevant service after deployment.
+
+## Rebirth sync coupling
+
+Fork sync and CompAII rebirth sync go together. After a meaningful Hermes fork sync or deploy, also run the rebirth sync from the CompAII state repository:
+
+```bash
+python ~/Projects/compaii-state/sync.py
+```
+
+## Verification checklist
+
+Before declaring a branch/workflow update complete:
+
+1. `git remote -v` confirms `origin` and `upstream`.
+2. `git status --short --branch` is clean.
+3. Every canonical feature branch is either rebased onto `nousmain` or explicitly documented as pending rebase.
+4. `main` contains every canonical active branch.
+5. Superseded remote branches are deleted or clearly documented as archives.
+6. Tests relevant to the changed areas pass via `scripts/run_tests.sh`.
+7. Deployed checkout `~/.hermes/hermes-agent` matches `origin/main` when runtime behavior changed.