Configura agentes, presets, transporte

Detecta los CLIs de agentes instalados, elige presets de lanzamiento, y decide como se autentica y se comunica cada uno con Orchemax.

Objetivo#

Decirle a Orchemax que CLIs de agentes de codigo hay en tu maquina, como lanzar cada uno (despacho headless vs. TUI nativo), que credenciales debe usar, y — para los pocos que lo soportan — como manejarlo via Agent Client Protocol (ACP) en vez de leer un pipe de subproceso.

Pasos#

Escanea tu PATH buscando CLIs de agentes conocidos (Claude, OpenCode, Cursor, Codex, Copilot, …):
```
orch agents scan
```
Escribe un snapshot; todavia no toca orch.yaml.
Revisa que se encontro:
```
orch agents show
```
Aplica las nuevas detecciones a orch.yaml (nunca sobrescribe presets que ya editaste):
```
orch agents apply
```

Los presets viven en dos mapas dentro de orch.yaml:

agents.cmds.<preset> — plantilla headless BYO usada por los workers despachados, ej. claude -p "{{prompt}}". Vienen incorporados copilot, claude, opencode, grok, kimi, commandcode, agy, codex y cursor.
agents.interactive.<preset> — lanzamiento de TUI nativo usado por orch <preset> (no requiere prompt), ej. codex, cursor-agent, claude, opencode --hostname 127.0.0.1 --port {{notify_port}}.
agents.workers — roster opcional de workers baratos que el Chair prefiere al despachar (CLI del agente + modelo del gateway). El orden de la lista es la preferencia. Los workers se miden con orch.agents.concurrent. Los Chairs abiertos se miden con orch.agents.max (Starter 2, Professional 5, Team 10). Los Chairs solo-MCP no consumen el medidor de workers.

Déjalo apagado con lista vacía u omitiendo la clave (entonces el Chair usa su propio agente). Un orch setup nuevo siembra agents.auth para dejar explícitos login/plan vs API-key.

Pi (workers con modelos externos): pon agent: pi en el roster o despacha dispatch_worker {agent: "pi", model: "..."}. Orchemax instala automáticamente Pi cuando utilizas workers con diferentes LLMs a la principal (pin @earendil-works/pi-coding-agent bajo machine-home tools/pi/<version>: requiere Node ≥ 22.19). El worker corre en su propio worktree, así que solo se le factura a su modelo esa subtarea y la ventana del Chair no crece con ella. El conteo de tokens por asiento está en /app/board. Omite la instalación automática con ORCH_SKIP_PI_ENSURE=1.

agents:
  auth:
    cursor: account          # login del plan — sin API key del gateway
    claude: account
    codex: account
    agy: account
    gemini: account
    opencode: gateway        # API-key / BYO → gateway local
    openclaude: gateway
    commandcode: gateway
    pi: gateway
  workers: []                # o rellena: agent + model/tier opcional
  # workers baratos opt-in, p.ej.:
  # workers:
  #   - agent: pi
  #     model: deepseek-v4.1-flash
  #     name: cheap-pi
  #     tier: cheap

Flags interactivas de Cursor (--approve-mcps --trust) viven en el preset built-in — solo sobrescribe si necesitas otras:

agents:
  interactive:
    cursor: cursor-agent --approve-mcps --trust

Roster opcional de workers (placeholders your-*-here nunca despachan):

agents:
  workers:
    - agent: claude
      model: sonnet              # LLM default del vendor (carril account)
      name: plan-login
      tier: account
    - agent: opencode
      model: deepseek-v4-flash   # LLM del gateway → orchemax/<id>
      name: api-key
      tier: cheap

tier: account — login/plan del vendor; model es el LLM default del vendor; sin API key. tier / auth: opcionales fijan el modo al spawn.
tier: cheap (gateway) — el gateway elige keys; en OpenCode la cuenta default del provider es orchemax. Mezcla filas account + gateway.
Los workers son trabajo secundario dentro de un proyecto. Otros Chairs de proyecto abiertos → bus to_project (ver Mismo CLI, varios proyectos), no workers suplentes.

entitlements_status.workers muestra el roster vivo al Chair. dispatch_worker {agent, model, prompt} puede pasar ambos de esa lista.

Edita cualquiera de los dos mapas directamente en orch.yaml para agregar un CLI que Orchemax no conoce, o para cambiar una plantilla existente. Si despachas un preset de CLI reconocido que no tiene entrada agents.cmds.<preset>, Orchemax falla en voz alta hacia el Chair (preset "<preset>" has no headless command: set agents.cmds.<preset>) en vez de correr el agente stub en silencio — agrega la entrada para resolverlo.

Un preset headless tambien debe cargar de verdad el servidor MCP propio de Orchemax desde el worktree (.cursor/mcp.json / .mcp.json / .orch/mcp.json), no solo correr — si no, toda herramienta del lado worker (msg_send, verify_report, lock_acquire, symbols) queda muerta toda la sesion.

orch agents apply aplica ajuste fino por categoria segun el agente (traits del catalogo): pointers GEMINI.md, avisos de auth por login, flags headless (--add-dir, --approve-mcps), y el siguiente paso si hace falta wire USER-scope. Nunca escribe configs de usuario sin consentimiento.

Categoria	Efecto	Agentes (ej.)
MCP de proyecto	Carga `.mcp.json` / `.cursor/mcp.json` del worktree	cursor, copilot, claude, opencode
MCP global (USER)	Un solo registro de maquina — requiere consentimiento	agy
Auth login	No uses API key en keys.env	agy, gemini
Headless `--add-dir`	Ancla escrituras al worktree	agy
Headless `--approve-mcps`	MCP de proyecto cargado sin UI	cursor
Interactivo `--approve-mcps --trust`	Evita el TUI de whitelist MCP de Cursor en `orch cursor`	cursor
Auto-aprobación de tools	Suprime prompts interactivos (gobernado por Orchemax)	agy, cursor, opencode

copilot lee .mcp.json del workspace por su cuenta; cursor necesita --approve-mcps en interactivo y headless (si no, el MCP de proyecto queda "not loaded (needs approval)", y el TUI de Approve a menudo se congela — ver common-seat-tune-ups y troubleshooting.md). agy no lee ningun archivo MCP por workspace — tiene una sola config global de maquina — asi que Orchemax registra una unica entrada global solo cuando lo pides:

orch guard wire --agy --scope user --allow-user-scope

Eso corre agy mcp add orch <ejecutable de orch> mcp, que agy documenta como "add or update": volver a correrlo reemplaza la entrada orch y deja intactos tus otros servidores MCP. orch setup no lo hace (USER-scope nunca va en setup). Tras orch agents apply, si agy esta entre los aplicados, la CLI imprime ese comando. La entrada no lleva ningun argumento de workspace a proposito — todos los workers agy de la maquina comparten la misma — y orch mcp deduce a que workspace pertenece desde ORCH_CONFIG (dispatch lo inyecta en cada worker, junto con ORCH_SESSION para la identidad del worker), y si falta sube directorio por directorio desde el cwd. Dos workers en dos workshops distintos pueden usar esa unica entrada al mismo tiempo.

Verificalo con agy mcp list (orch stdio enabled …). Si falta o esta deshabilitada, un worker agy igual corre y igual sale con codigo 0 — con cero herramientas de Orchemax y sin nada en su log que lo diga — asi que Orchemax cierra la sesion con guardrails: fail y orch MCP unavailable in worker — run orch guard wire --agy --scope user --allow-user-scope.

agy tambien necesita --add-dir "{{worktree}}" en su preset headless (el default ya lo trae): agy no trata su cwd como el workspace, y sin el flag escribe en ~/.gemini/antigravity-cli/scratch/ y deja el worktree intacto.

Permisos de herramientas y supresión de confirmaciones: Dado que Orchemax ya gobierna el aislamiento en ramas temporales de git, .sandbox/ y las puertas de verificación, los CLIs hijos corren con flags de auto-aprobación para que los workers desatendidos y los asientos interactivos no sean interrumpidos por preguntas constantes para cada comando o tool. Para Antigravity, Orchemax inyecta --dangerously-skip-permissions tanto en workers headless como en asientos interactivos orch agy. Cursor interactivo usa --approve-mcps --trust; headless también --force (y --output-format json). OpenCode usa run --auto. Cualquier CLI propio (BYO) puede definir sus propios flags en agents.interactive.<preset> y agents.cmds.<preset> (las allowlists del vendor suelen re-preguntar cuando Orchemax reescribe el MCP — ver common-seat-tune-ups).

Elige el modo de credenciales por preset con agents.auth.<preset>:

account — el agente mantiene su propio login de plan (Cursor, Claude Pro/Max, Codex, …); Orchemax solo inyecta ORCH_GATEWAY_* propias, nunca claves de proveedor. El gateway no aplica al tráfico de modelos.
gateway — el agente se autentica con la llave virtual de Orchemax y el tráfico de modelos pasa por el gateway local (solo asientos con API key / proveedor BYO: OpenCode, OpenClaude, Command Code, BYOK, …).

Por defecto: codex y cursor son account. claude es gateway solo cuando hay una llave passthrough de Anthropic; si no, account. El resto de asientos BYO / API key tiende a gateway (OpenAI-compat es el cable por defecto).

Cablear el gateway por protocolo, no por nombre de CLI:

Protocolo	Comando
Cuenta / plan (Cursor, Claude plan, Codex)	— (conserva el login)
OpenAI-compat (OpenCode, OpenClaude, Command Code, BYOK, …)	`orch gateway connect` / `openai`
Escritura OpenCode (opcional)	`orch gateway connect opencode --allow-user-scope`
Anthropic Messages (Claude + API key)	`orch gateway connect anthropic`

Matriz completa: gateway-keys-and-connect.md.

agents.route.<preset> es el interruptor hermano para los CLIs que leen su propio archivo de configuracion, hoy OpenCode. Sin definir, un worker OpenCode despachado recibe un OPENCODE_CONFIG propiedad de Orchemax apuntando al gateway local solo si ese gateway tiene un proveedor vivo (ai.mode: live y al menos una llave de proveedor); si no, el log deja route: opencode-native (workspace gateway has no live provider) y el CLI se queda con su propia configuracion, que Orchemax nunca escribe. Para forzar cualquiera de los dos lados:

agents:
  route:
    opencode: gateway   # o: native

Arrancar el proxy no es consentimiento para editar tu perfil: orch gateway run no escribe ~/.config/opencode/opencode.json ni el ORCH_GATEWAY_KEY de usuario. Eso le toca a orch setup y a orch guard wire --opencode --scope user --allow-user-scope, que respaldan lo que tocan en <archivo>.bak-<timestamp>.

Para los CLIs que exponen un modo servidor Agent Client Protocol — actualmente gemini (gemini --acp) y opencode (opencode acp) — configura:
```
agents:
  transport:
    gemini: acp
```
ACP hace visibles para Orchemax las llamadas a herramientas y los prompts de permiso, en vez de leer stdout. Cualquier otro preset se queda en el transporte subprocess por defecto; agents.acp.<preset> guarda la invocacion que Orchemax corre para poner ese CLI en modo ACP (incorporada para gemini/opencode, vacia para el resto — un preset sin entrada ACP no puede usar transport: acp).

Define los limites de ejecucion:

agents:
  timeout_sec: 600        # tope de reloj por ejecucion (0 = default)
  idle_timeout_sec: 0     # mata si no hay stdout/stderr por este tiempo; 0 = el default interno (420s), negativo = apagado

AGENTS.md — un solo archivo de instrucciones para cada CLI#

orch init, orch project add y orch setup escriben un AGENTS.md compacto (menos de 1.5 KB) en la raiz de cada proyecto registrado: el locale/code_lang del proyecto, que gates guard.* estan activos, la regla de sandbox del item 144, y como llegar a Orchemax (el servidor MCP orch, o el CLI orch). El contenido vive dentro de un bloque  … , asi que una nueva corrida siempre lo refresca sin tocar nada que agregues fuera de los marcadores.

Cada CLI que Orchemax administra lo lee, solo en el alcance del proyecto:

Codex, OpenCode — leen AGENTS.md de forma nativa; no hace falta nada mas.
Claude Code — el CLAUDE.md del proyecto trae un include @AGENTS.md.
Cursor — .cursor/rules/orch.mdc (alwaysApply: true) apunta ahi.
Copilot — .github/copilot-instructions.md apunta ahi.
Gemini / agy — GEMINI.md apunta ahi.

Revisa que esta leyendo cada CLI con:

orch harness scan

que imprime una fila por CLI por proyecto — el archivo que lee, y si ese archivo todavia apunta a AGENTS.md.

Verificar#

orch <preset>

lanza el TUI nativo de ese preset. Para un despacho headless, revisa .orch-agent.log en el worktree de la sesion para ver el comando resuelto y cualquier codigo de salida por permiso/timeout (124 = agents.timeout_sec/idle timeout, 126 = un prompt de permiso headless que Orchemax no pudo responder).

Deshacer#

Quita la entrada del preset de agents.cmds / agents.interactive, o regresa agents.auth.<preset> / agents.transport.<preset> a sin definir para volver a los valores por defecto de arriba.

Relacionado#

Ajustes comunes del asiento — UI de terminal que maneja Orchemax, modelo de OpenClaude, dontAsk vs bypassPermissions, Notification, tope de turnos
gateway-keys-and-connect.md — que es lo que realmente enruta agents.auth: gateway (matriz OpenCode / OpenClaude / Claude / …).
../talk-to-orch/connect-openclaude-gateway.md — receta OpenClaude.
troubleshooting.md — timeouts de permiso en workers.