diff --git a/docs/DOCS-MAINTENANCE.md b/docs/DOCS-MAINTENANCE.md index 9cde5f39..b71804c6 100644 --- a/docs/DOCS-MAINTENANCE.md +++ b/docs/DOCS-MAINTENANCE.md @@ -93,10 +93,6 @@ Prefer relative repo links for internal docs: Use full URLs only for external resources and public community links. -## Translations - -`docs/es/` (Spanish) and `docs/ru/` (Russian) are partial translations of the English tree. They lag behind English (last synced around 2026-06-24) and are updated in dedicated translation-sync passes, not with every English change. The English pages are authoritative whenever a translation disagrees. - ## Diagrams Mermaid diagrams are allowed. Keep them small enough to read in GitHub's Markdown renderer. diff --git a/docs/es/API-CONTRACT.md b/docs/es/API-CONTRACT.md deleted file mode 100644 index 36d505b3..00000000 --- a/docs/es/API-CONTRACT.md +++ /dev/null @@ -1,337 +0,0 @@ ---- -title: "Contrato de la API local de Coven (coven.daemon.v1)" -description: "El contrato versionado coven.daemon.v1 bajo /api/v1: negociación de health, descubrimiento de capabilities, sobres de error y reglas de compatibilidad aditiva." ---- - -# Contrato de la API local de Coven - -La API por socket del daemon de Coven es un límite de compatibilidad público para comux y clientes externos como external OpenClaw bridge plugin. - -## Versión estable actual - -- `GET /api/v1/health` expone `apiVersion: "coven.daemon.v1"`, `covenVersion` y un objeto `capabilities` legible por máquina. -- Los clientes deben leer `/api/v1/health` antes de asumir cualquier forma de respuesta de otros endpoints. -- Las rutas heredadas sin versión como `GET /health` siguen siendo alias del MVP temprano; los nuevos clientes deberían usar `/api/v1`. -- Los clientes del plano de control deben descubrir capabilities antes de enviar ids de acción. -- Todos los fallos de la API se devuelven como sobres estructurados `{ "error": { "code", "message", "details" } }`. -- Los eventos incluyen un cursor monótono `seq` para lecturas incrementales. - -## `GET /api/v1/health` - -`GET /api/v1/health` devuelve la accesibilidad del daemon, la versión nombrada del contrato, la versión de coven y capabilities legibles por máquina: - -```json -{ - "ok": true, - "apiVersion": "coven.daemon.v1", - "covenVersion": "0.0.0", - "capabilities": { - "sessions": true, - "events": true, - "eventCursor": "sequence", - "structuredErrors": true - }, - "daemon": { - "pid": 12345, - "startedAt": "2026-05-09T06:43:00Z", - "socket": "/Users/alice/.coven/coven.sock" - } -} -``` - -Si los metadatos del daemon no están disponibles, `daemon` puede ser `null`. - -### Campos de capability - -| Campo | Tipo | Descripción | -|-------------------|---------|-------------------------------------------------------------------| -| `sessions` | boolean | La API de sesiones (`/sessions`, `/sessions/:id`) está disponible. | -| `events` | boolean | La API de eventos (`/events`) está disponible. | -| `eventCursor` | string | Tipo de cursor soportado; `"sequence"` significa que `afterSeq` es estable. | -| `structuredErrors`| boolean | Todos los errores usan la forma `{ error: { code, message, details } }`. | - -## Sobre estructurado de error - -```mermaid -flowchart TD - Req[Incoming request] --> Parse{Parse + version check} - Parse -- bad shape --> ErrInvalid["400 invalid_request"] - Parse -- unknown version --> ErrInvalid - Parse -- ok --> Route{Route exists?} - Route -- no --> ErrNotFound["404 not_found"] - Route -- yes --> Validate{Field validation} - Validate -- cwd outside root --> ErrInvalid - Validate -- unknown harness/action --> ErrInvalid - Validate -- ok --> Action{Resource lookup} - Action -- session missing --> ErrSession["404 session_not_found"] - Action -- session not live --> ErrLive["409 session_not_live"] - Action -- launch (PTY/pipe spawn, init write, harness startup) fails --> ErrLaunch["500 launch_failed"] - Action -- send_input fails --> ErrSend["500 send_input_failed"] - Action -- kill_session fails --> ErrKill["500 kill_failed"] - Action -- runtime down --> ErrRuntime["503 runtime_unavailable"] - Action -- internal panic --> ErrInternal["500 internal_error"] - Action -- ok --> Success[Documented success shape] - - ErrInvalid & ErrNotFound & ErrSession & ErrLive & ErrLaunch & ErrSend & ErrKill & ErrRuntime & ErrInternal -->|"{ error: { code, message, details } }"| Client[Client branches on code] -``` - -Todos los errores de la API usan el siguiente sobre estable. Los clientes deben ramificar en `error.code`, no en `error.message`: - -```json -{ - "error": { - "code": "session_not_found", - "message": "Session was not found.", - "details": { - "sessionId": "abc-123" - } - } -} -``` - -`details` es opcional y se incluye cuando aporta contexto útil. - -### Códigos de error estables - -| Código | Estado HTTP | Descripción | -|------------------------|-------------|--------------------------------------------------| -| `not_found` | 404 | Ruta genérica no encontrada. | -| `invalid_request` | 400 o 404 | Petición mal formada, id de harness desconocido, campo obligatorio ausente, o versión de API no compatible. | -| `session_not_found` | 404 | El id de sesión no existe. | -| `session_not_live` | 409 | La sesión existe pero no está en ejecución. | -| `project_root_violation`| 400 | Reservado. Las violaciones de cwd actualmente emiten `invalid_request`; promover a un código propio permitiría a los clientes ramificar sin parsear el mensaje. | -| `pty_spawn_failed` | 500 | Reservado. Los fallos de spawn de PTY actualmente emiten `launch_failed`; promover a un código propio distinguiría "no se pudo abrir el PTY" de "el CLI del harness falló al iniciar". | -| `launch_failed` | 500 | El daemon aceptó la petición pero el runtime (PTY/pipe spawn, escritura inicial, arranque del CLI) falló. `details.sessionId` es la fila insertada y marcada como `failed`. | -| `send_input_failed` | 500 | El daemon aceptó el payload de input pero la escritura del runtime falló (pipe cerrado, proceso muerto, error de IO). `details.sessionId` es la sesión afectada. | -| `kill_failed` | 500 | El daemon aceptó la petición de kill pero la señal/llamada del runtime falló (permisos, proceso ausente, error de IO). `details.sessionId` es la sesión afectada. | -| `runtime_unavailable` | 503 | El runtime de la sesión no está disponible. | -| `internal_error` | 500 | Error interno inesperado. | - -## Forma del catálogo de capabilities (`v1`) - -`GET /api/v1/capabilities` devuelve el catálogo de capabilities del daemon/plano de control. Este es el handshake previsto para el cliente de chat/captura al decidir qué acciones mostrar o enrutar a través de Coven. - -```json -{ - "capabilities": [ - { - "id": "coven.control.actions", - "label": "Coven control-plane action router", - "adapter": "coven-daemon", - "status": "available", - "policy": "allow", - "actions": ["coven.capabilities.refresh"] - }, - { - "id": "desktop.automation", - "label": "Desktop automation adapters", - "adapter": "desktop-use", - "status": "planned", - "policy": "requiresApproval", - "actions": [] - } - ] -} -``` - -Valores enum conocidos en `v1`: - -- `status`: `available`, `planned` -- `policy`: `allow`, `requiresApproval` - -Los clientes deben ignorar ids de capability e ids de acción futuros desconocidos a menos que los soporten explícitamente. - -## Forma de acción de control (`v1`) - -`POST /api/v1/actions` acepta un sobre de acción con forma de política. El daemon valida el id de acción antes de permitir cualquier trabajo del adaptador. - -```json -{ - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "args": {} -} -``` - -Las acciones seguras completadas inmediatamente devuelven `200`: - -```json -{ - "ok": true, - "accepted": true, - "action": "coven.capabilities.refresh", - "status": "completed", - "event": { - "kind": "capabilities.refreshed", - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "payload": { "capabilities": 3 } - } -} -``` - -Los ids de acción desconocidos devuelven `400` y fallan en cerrado: - -```json -{ - "ok": false, - "accepted": false, - "action": "desktop.deleteEverything", - "status": "rejected", - "reason": "unknown action `desktop.deleteEverything`" -} -``` - -## Forma del registro de sesión (`v1`) - -En `v1`, las respuestas de sesión se mantienen como objetos JSON crudos usando los nombres snake_case de los campos del daemon en Rust. - -Endpoints que devuelven esta forma: - -- `GET /api/v1/sessions` → `SessionRecord[]` -- `POST /api/v1/sessions` → `SessionRecord` -- `GET /api/v1/sessions/:id` → `SessionRecord` - -```json -{ - "id": "session-1", - "project_root": "/repo", - "harness": "codex", - "title": "Fix the tests", - "status": "running", - "exit_code": null, - "archived_at": null, - "created_at": "2026-05-09T06:43:00Z", - "updated_at": "2026-05-09T06:43:05Z" -} -``` - -## Forma del registro de evento y paginación por cursor (`v1`) - -`GET /api/v1/events` devuelve un sobre paginado con cursores monótonos `seq`. - -### Parámetros de query - -| Parámetro | Requerido | Descripción | -|---------------|-----------|---------------------------------------------------------| -| `sessionId` | Sí | Sesión de la cual obtener eventos. | -| `afterSeq` | No | Devuelve solo eventos con `seq > afterSeq` (preferido). | -| `afterEventId`| No | Cursor de compatibilidad — se resuelve a una posición de secuencia. | -| `limit` | No | Número máximo de eventos a devolver (impuesto por el daemon, máx. 1000). | - -### Sobre de respuesta - -```json -{ - "events": [ - { - "seq": 42, - "id": "event-uuid", - "session_id": "session-uuid", - "kind": "output", - "payload_json": "{\"data\":\"hello\"}", - "created_at": "2026-05-09T06:43:10Z" - } - ], - "nextCursor": { - "afterSeq": 42 - }, - "hasMore": false -} -``` - -`nextCursor` es `null` cuando no hay eventos. `hasMore` es `true` cuando se aplicó un `limit` y pueden existir más eventos. - -### Patrón de lectura incremental - -1. Sondea `GET /events?sessionId=` para obtener todos los eventos (con `limit` opcional). -2. Usa `nextCursor.afterSeq` en peticiones posteriores: `GET /events?sessionId=&afterSeq=`. -3. Repite hasta que `hasMore` sea `false`. - -Esto da a los clientes lecturas incrementales estables. La entrega exactly-once también requiere checkpointing del lado del cliente e idempotencia. - -```mermaid -sequenceDiagram - participant Client - participant Daemon as /api/v1/events - - Client->>Daemon: GET ?sessionId=S1 - Daemon-->>Client: { events: [seq 1..50], nextCursor: { afterSeq: 50 }, hasMore: true } - Client->>Client: persist last seq = 50 - Client->>Daemon: GET ?sessionId=S1&afterSeq=50 - Daemon-->>Client: { events: [seq 51..78], nextCursor: { afterSeq: 78 }, hasMore: false } - Client->>Client: persist last seq = 78 - - note over Client,Daemon: Client crash + restart - Client->>Daemon: GET ?sessionId=S1&afterSeq=78 - Daemon-->>Client: { events: [seq 79..82], nextCursor: { afterSeq: 82 }, hasMore: false } -``` - -Persistir `afterSeq` sobrevive a los reinicios del daemon: los eventos son append-only y los números seq son monótonos, así que un sondeo reanudado siempre retoma donde se detuvo. - -## Formas de respuesta de control en vivo (`v1`) - -Ambos endpoints de control en vivo devuelven la misma forma de respuesta aceptada en caso de éxito: - -- `POST /api/v1/sessions/:id/input` -- `POST /api/v1/sessions/:id/kill` - -```json -{ - "ok": true, - "accepted": true -} -``` - -Las respuestas no exitosas compartidas usan el sobre estructurado de error: - -- `404` cuando la sesión no existe: - -```json -{ - "error": { - "code": "session_not_found", - "message": "Session was not found.", - "details": { "sessionId": "session-1" } - } -} -``` - -- `409` cuando la sesión existe pero no está viva: - -```json -{ - "error": { - "code": "session_not_live", - "message": "Session is not live.", - "details": { "sessionId": "session-1" } - } -} -``` - -## Compatibilidad con comux y el puente OpenClaw - -- comux lee el objeto `capabilities` desde `/health` para decidir qué funciones usar. -- El puente OpenClaw external OpenClaw bridge plugin (`packages/openclaw-coven`) se actualiza en este repo junto con el daemon y usa `apiVersion === "coven.daemon.v1"` como su guardia de contrato. -- Las actualizaciones de cliente para usar cursores `afterSeq` y sobres de eventos paginados pueden ocurrir independientemente de la actualización del daemon; la forma impuesta por el daemon es la fuente de verdad. -- El campo `supportedApiVersions` se ha eliminado de la respuesta de health en `coven.daemon.v1`; los clientes deben comprobar `apiVersion` directamente. - -## Política de compatibilidad y migración - -- Los clientes de `coven.daemon.v1` pueden depender de los nombres de campos documentados y las formas de respuesta de nivel superior anteriores. -- Los campos aditivos son retrocompatibles. Los clientes deben ignorar campos desconocidos cuando sea seguro. -- Cualquier cambio incompatible debe entregarse bajo un nuevo valor de `apiVersion` expuesto por `GET /api/v1/health` o su ruta sucesora. -- Antes de que un cliente cambie a un nuevo contrato mayor, el repo de Coven debe publicar docs de contrato actualizadas y una nota de migración que mapee la forma vieja a la nueva. - -## Handshake recomendado del cliente - -1. Llamar a `GET /api/v1/health`. -2. Verificar `apiVersion === "coven.daemon.v1"` y `capabilities.structuredErrors === true`. -3. Comprobar `capabilities.eventCursor === "sequence"` antes de usar paginación con `afterSeq`. -4. Solo entonces depender de las formas documentadas de sesiones/eventos de `v1`. - -## Límite del alcance - -El contrato `coven.daemon.v1` cubre health del daemon, descubrimiento de capabilities, enrutamiento de acciones, sesiones, eventos, input en vivo y kill en vivo. No trates futuros nombres de rutas de orquestación, handoff o enrutamiento de tareas como API reservada hasta que estén implementados y documentados en este archivo. diff --git a/docs/es/API.md b/docs/es/API.md deleted file mode 100644 index bd5eacff..00000000 --- a/docs/es/API.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "API por socket local de Coven" -description: "La API HTTP local de Coven servida sobre un socket Unix: health, capabilities, actions, sessions, events y reenvío de input bajo /api/v1." ---- - -# API local de Coven - -_Última actualización: 2026-05-09_ - -Coven expone una pequeña API HTTP sobre el socket Unix local en `/coven.sock`. El daemon en Rust es el límite de autoridad: los clientes pueden validar para mejorar la UX, pero el daemon sigue validando raíces de proyecto, cwd, ids de harness, ids de sesión, input y estado de sesión viva antes de actuar. - -```mermaid -flowchart LR - Client[Local client] -->|connect| Sock["/coven.sock"] - Sock -->|HTTP/1.1| Router["/api/v1 router"] - Router --> Health["/health"] - Router --> Capabilities["/capabilities"] - Router --> Actions["/actions"] - Router --> Sessions["/sessions[/:id[/input|/kill]]"] - Router --> Events["/events"] - Router --> Version["/api-version"] - - Health & Capabilities & Actions & Sessions & Events & Version -->|"{ ... } or { error: { code, message, details } }"| Client -``` - -Cada ruta devuelve o bien una forma de éxito documentada o el sobre estructurado de error. Las rutas desconocidas, los ids de acción desconocidos y las versiones de API desconocidas fallan en cerrado con `invalid_request` o `not_found`. - -Consulta [Autenticación y acceso local](/AUTH) para conocer la postura de auth actual. En resumen: la API del daemon no usa OAuth, JWT, bearer tokens, API keys ni cookies hoy. El acceso se basa en el socket Unix local, las credenciales del proveedor se quedan con las CLIs de harness, y cualquier exposición remota, de navegador o TCP necesita un diseño de auth separado. - -## Versionado - -El contrato público actual de la API es el contrato nombrado **`coven.daemon.v1`** servido bajo el prefijo de ruta `/api/v1`. - -Los clientes versionados deben usar el prefijo `/api/v1`: - -| Endpoint | Propósito | -|---|---| -| `GET /api/v1/api-version` | Leer la versión de API activa y las versiones compatibles | -| `GET /api/v1/health` | Comprobar la salud y metadatos del daemon | -| `GET /api/v1/capabilities` | Descubrir capabilities del daemon/plano de control y pistas de política | -| `POST /api/v1/actions` | Enrutar una acción de plano de control con forma de política | -| `GET /api/v1/sessions` | Listar sesiones activas | -| `POST /api/v1/sessions` | Lanzar una sesión | -| `GET /api/v1/sessions/:id` | Obtener una sesión | -| `GET /api/v1/events?sessionId=...` | Leer eventos de sesión | -| `POST /api/v1/sessions/:id/input` | Reenviar input a una sesión viva | -| `POST /api/v1/sessions/:id/kill` | Matar una sesión viva | - -Las rutas no versionadas siguen actualmente como alias heredados durante la ventana inicial del MVP, pero los nuevos clientes no deberían depender de ellas. - -Los prefijos `/api//...` desconocidos fallan en cerrado con una respuesta JSON `unsupported API version`. - -## Respuesta de health - -`GET /api/v1/health` devuelve la versión de la API junto con el estado del daemon: - -```json -{ - "ok": true, - "apiVersion": "coven.daemon.v1", - "covenVersion": "0.0.0", - "capabilities": { - "sessions": true, - "events": true, - "eventCursor": "sequence", - "structuredErrors": true - }, - "daemon": { - "pid": 12345, - "startedAt": "2026-05-09T12:00:00Z", - "socket": "/Users/example/.coven/coven.sock" - } -} -``` - -Cuando no haya metadatos del daemon disponibles, `daemon` es `null`. - -## Capabilities del plano de control - -`GET /api/v1/capabilities` es el punto de descubrimiento para clientes de primera parte como el cliente de chat/captura. Devuelve ids de capability, propiedad del adaptador, disponibilidad, pistas de política e ids de acción. Esto evita que los clientes hardcodeen lo que el daemon puede hacer. - -```json -{ - "capabilities": [ - { - "id": "coven.control.actions", - "label": "Coven control-plane action router", - "adapter": "coven-daemon", - "status": "available", - "policy": "allow", - "actions": ["coven.capabilities.refresh"] - }, - { - "id": "desktop.automation", - "label": "Desktop automation adapters", - "adapter": "desktop-use", - "status": "planned", - "policy": "requiresApproval", - "actions": [] - } - ] -} -``` - -## Acciones del plano de control - -`POST /api/v1/actions` acepta un sobre de intent estilo cliente de captura. El daemon solo enruta acciones conocidas; las acciones desconocidas fallan en cerrado antes de que pueda ejecutarse cualquier adaptador. - -```json -{ - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "args": {} -} -``` - -Las acciones seguras completadas inmediatamente devuelven `200` con un payload con forma de evento que los clientes pueden renderizar de forma optimista o integrar en flujos de eventos posteriores: - -```json -{ - "ok": true, - "accepted": true, - "action": "coven.capabilities.refresh", - "status": "completed", - "event": { - "kind": "capabilities.refreshed", - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "payload": { "capabilities": 3 } - } -} -``` - -## Reglas de compatibilidad - -- Se permiten campos JSON aditivos en las respuestas de `v1`. -- Los campos requeridos existentes no deben eliminarse ni renombrarse dentro de `v1`. -- Los cambios de forma de respuesta o comportamiento que rompan compatibilidad requieren un nuevo prefijo de versión de API. -- Los clientes externos deben llamar a `/api/v1/health` antes de asumir compatibilidad. -- Los cambios en el daemon que afecten al comportamiento de `/api/v1/health`, `/api/v1/sessions`, `/api/v1/events`, input o kill deben actualizar los tests de compatibilidad de cliente en el mismo repo. diff --git a/docs/es/ARCHITECTURE.md b/docs/es/ARCHITECTURE.md deleted file mode 100644 index d6aafcf6..00000000 --- a/docs/es/ARCHITECTURE.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "Arquitectura del runtime de Coven" -summary: "Cómo se componen el daemon en Rust, la CLI, la TUI, el cockpit comux y el plugin OpenClaw de Coven alrededor de la API por socket local, los adaptadores PTY y el almacén de eventos." -read_when: - - Entender la topología del runtime de Coven - - Diseñar un cliente alrededor de la API por socket local -description: "Topología del runtime Coven: daemon en Rust, CLI, TUI, comux y OpenClaw alrededor de la API por socket local, los adaptadores PTY y el almacén de eventos." ---- - -# Arquitectura de Coven - -Coven es un sustrato de harness local-first. La CLI/daemon en Rust es la capa de autoridad; los clientes como la TUI de la CLI, comux y el plugin opcional OpenClaw son capas de presentación/integración. - -El contrato versionado de la API por socket local vive en [`docs/API-CONTRACT.md`](/API-CONTRACT). Los clientes deben usar `GET /api/v1/health` y negociar contra `apiVersion: "coven.daemon.v1"` y el objeto `capabilities` antes de depender de las formas de respuesta de sesiones o eventos. Todas las respuestas de error usan el sobre estructurado `{ error: { code, message, details } }` documentado allí. - -## Topología del runtime - -```mermaid -flowchart LR - User[Developer] --> CLI[coven CLI / TUI] - CLI -->|direct commands| Rust[Coven Rust CLI] - Rust --> Daemon[Coven daemon] - - Comux[comux cockpit] -->|HTTP over Unix socket| Daemon - OpenClaw[OpenClaw] --> Plugin[external OpenClaw bridge plugin] - Plugin -->|HTTP over Unix socket| Daemon - ChatClient[chat/intent client] -->|capabilities + actions| Daemon - - Daemon --> Control[Control plane: capability discovery + action routing] - Control --> Policy[Policy + permission hints] - Control --> AdapterBus[Adapter/event bus] - AdapterBus -. desktop automation .-> DesktopUse[desktop-use adapters] - - Daemon --> Boundary[Project-root + cwd guard] - Boundary --> Adapter[Harness adapter router] - Adapter --> Codex[Codex PTY] - Adapter --> Claude[Claude Code PTY] - Adapter -. future .-> Future[Hermes / Aider / Gemini / custom adapters] - - Daemon --> Store[(SQLite session ledger)] - Daemon --> Events[(append-only event log)] - Codex --> Events - Claude --> Events -``` - -## Ciclo de vida de la sesión - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI/TUI - participant D as Rust daemon - participant S as SQLite store - participant H as Harness PTY - - U->>C: coven run codex "fix tests" - C->>D: POST /api/v1/sessions(projectRoot, cwd, harness, prompt) - D->>D: canonicalize projectRoot + cwd - D->>D: reject outside-root or unsupported harness - D->>S: create session metadata - D->>H: spawn validated argv in PTY - H-->>S: output / exit events - D-->>C: session id + running status - - U->>C: coven sessions - C->>S: list active sessions, or all with --all - C-->>U: interactive session browser - - U->>C: Rejoin / View Log / Summon / Archive / Sacrifice - C->>D: attach/input/kill when live - C->>S: archive/summon/sacrifice non-live session rituals -``` - -## Límite de autoridad - -```mermaid -flowchart TD - Client[CLI, TUI, comux, OpenClaw plugin] --> Request[Launch / input / kill / list request] - Request --> Rust[Rank 0 authority: Rust daemon] - Rust --> RootCheck{projectRoot explicit?} - RootCheck -- no --> RejectRoot[Reject] - RootCheck -- yes --> CwdCheck{cwd canonicalized inside root?} - CwdCheck -- no --> RejectCwd[Reject] - CwdCheck -- yes --> HarnessCheck{harness allowlisted?} - HarnessCheck -- no --> RejectHarness[Reject with install hint] - HarnessCheck -- yes --> Spawn[Spawn harness with argv APIs] - Spawn --> Ledger[Persist session + events] -``` - -## Límite de captura / automatización - -El cliente de chat/captura debe seguir siendo una interfaz de chat, una superficie de renderizado optimista/eco local, una capa de captura de intenciones y un host pequeño y rápido para acciones locales ultra simples. No debe convertirse en el motor de automatización. - -Coven es el runtime local compartido canónico para la automatización reutilizable porque centraliza: - -- la propiedad del daemon/procesos -- las decisiones de política y permisos -- el almacenamiento de configuración/perfiles -- el descubrimiento de capacidades -- el enrutamiento de acciones y la emisión de eventos -- la propiedad de adaptadores para Accessibility, AppleScript, teclado/ratón, ventanas, sistema de archivos, portapapeles y puentes específicos de aplicaciones - -El flujo previsto es: - -```text -user -> chat/capture client -> Coven -> adapters -> desktop/apps -desktop/apps -> Coven -> chat/capture client UI updates -``` - -`GET /api/v1/capabilities` permite al cliente de chat/captura y a otros clientes descubrir qué puede enrutar Coven. `POST /api/v1/actions` ofrece a los clientes un sobre de intención estable sin acoplarlos directamente a APIs frágiles de automatización del sistema operativo. - -## Límite de adaptadores futuros - -El runtime público actual de Coven es de un único harness por sesión. El daemon ya mantiene el límite de bajo nivel correcto para el trabajo de coordinación futuro: los clientes pueden descubrir capacidades, lanzar harnesses conocidos, leer eventos y preservar la imposición del project-root en Rust. - -No documentes los comandos de orquestación futuros como visibles para el usuario hasta que existan en la CLI y en la API por socket. Las capas de coordinación futuras deben construirse sobre el contrato actual de sesión/evento sin saltarse la validación del daemon. - ---- - -## Superficie actual visible para el usuario - -- `coven` y `coven tui` abren la paleta de slash-commands amigable para principiantes. -- `coven doctor` verifica el estado del store/proyecto/harness e imprime los próximos pasos. -- `coven daemon start/status/restart/stop` gestiona el daemon local. -- `coven run codex|claude ` lanza una sesión PTY con alcance al proyecto. -- `coven sessions` abre el navegador de sesiones para humanos en la terminal; `--plain` conserva la salida apta para scripts. -- Las acciones del navegador de sesiones presentan opciones legibles: **Rejoin**, **View Log**, **Summon**, **Archive** y **Sacrifice**. -- `coven attach|summon|archive|sacrifice ` siguen siendo verbos explícitos de más bajo nivel para scripts y flujos de copiar/pegar. - -## Resumen de distribución - -Los paquetes wrapper de npm se publican para los primeros adoptantes: - -- `@opencoven/cli` -- `@opencoven/cli-macos` -- `@opencoven/cli-linux-x64` -- `@opencoven/cli-windows` para Windows x64 - -Las versiones del paquete fuente permanecen como plantilla en el repositorio; el workflow de release dispatch proporciona la versión publicada y construye los paquetes de plataforma. Verifica el registro de npm y las releases de GitHub antes de hacer afirmaciones específicas de versión sobre las releases. diff --git a/docs/es/AUTH.md b/docs/es/AUTH.md deleted file mode 100644 index c6f62d0b..00000000 --- a/docs/es/AUTH.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Autenticación y acceso local" -description: "Coven usa un modelo de acceso por socket Unix local del mismo usuario en lugar de OAuth o API keys. Aprende qué protege /api/v1 y qué requiere el acceso remoto." ---- - -# Autenticación y acceso local - -_Última actualización: 2026-05-14_ - -Coven no tiene actualmente autenticación de usuario a nivel de daemon en el sentido de OAuth, JWT, bearer token, API key, cookie de navegador o cuenta alojada. - -La solución actual es un **modelo de acceso local del mismo usuario**: - -- El daemon expone HTTP solo sobre el socket Unix local en `/coven.sock`. -- La ruta de socket por defecto es `~/.coven/coven.sock`. -- Los clientes pueden validar peticiones para mejorar la UX, pero el daemon en Rust es el límite de aplicación. -- Las credenciales del proveedor del harness se quedan en el flujo de auth local normal del proveedor del harness. -- Coven no debe leer, proxificar, persistir ni emitir credenciales de Codex, Claude Code, OpenAI, Anthropic, GitHub u OpenClaw. - -Esta es intencionalmente una postura MVP local-first. Es adecuada para clientes locales del mismo usuario como la CLI/TUI de Coven, comux y el plugin externo OpenClaw. No es un esquema de auth de API remota. - -```mermaid -flowchart LR - subgraph User["Same-user trust zone"] - direction LR - CLI[coven CLI / TUI] - Comux[comux] - Plugin["OpenClaw bridge\nOpenClaw plugin"] - Other[Other same-user clients] - end - - CLI -->|Unix socket| Socket["/coven.sock"] - Comux -->|Unix socket| Socket - Plugin -->|Unix socket + trust-anchor checks| Socket - Other -->|Unix socket| Socket - - Socket --> Daemon["Rust daemon\n(authority boundary)"] - Daemon --> Store[("SQLite store + event log")] - Daemon --> PTY[Harness PTYs] - - Remote((Remote network)) -.-x|"REJECTED: no TCP, no auth design"| Daemon - Browser((Browser tab)) -.-x|"REJECTED: no origin policy"| Daemon - OtherUser((Another OS user)) -.-x|"REJECTED: socket permissions"| Daemon -``` - -El límite son los permisos del sistema de archivos más la localidad de procesos del mismo usuario. Cualquier cosa fuera de la zona discontinua se rechaza por diseño; introducir una superficie remota, de navegador o entre usuarios requiere un diseño de auth separado (no un túnel del socket existente). - -## Qué protege la API hoy - -### Localidad del socket Unix - -La API no se expone como TCP por defecto. Los clientes se conectan al socket Unix local propiedad del directorio de estado de Coven del usuario. - -Los nuevos clientes deben tratar la ruta del socket como el ancla de confianza y deben conectarse solo a la API versionada bajo `/api/v1/...`. - -### Comprobaciones de autoridad en Rust - -El daemon debe revalidar los campos sensibles de la petición antes de actuar, incluso cuando un cliente ya los haya validado: - -- versión de API; -- raíz de proyecto; -- directorio de trabajo; -- id de harness; -- id de sesión; -- estado de sesión viva; -- peticiones de input; -- peticiones de kill; y -- ids de acción del plano de control. - -Las versiones de API desconocidas, los ids de acción desconocidos, los harnesses no soportados, los ids de sesión inválidos y los directorios de trabajo fuera de raíz deben fallar en cerrado. - -### Auth del proveedor en manos del harness - -Coven lanza CLIs de harness local soportadas. No implementa el login del proveedor. - -Ejemplos: - -- La autenticación de Codex sigue siendo `codex login` o la configuración local propia de la CLI de Codex. -- La autenticación de Claude Code sigue siendo `claude doctor` o la configuración local propia de la CLI de Claude Code. - -`coven doctor` puede informar de pistas de configuración para estas herramientas, pero Coven no posee sus credenciales. - -### Salvaguardas del plugin externo OpenClaw - -La integración con OpenClaw se externaliza a través de external OpenClaw bridge plugin. El núcleo de OpenClaw no es una raíz de confianza de Coven. - -El plugin está deshabilitado por defecto y debe seleccionarse explícitamente como backend ACP. Valida el ancla de confianza del socket local antes de conectarse: - -- `covenHome` debe ser un directorio absoluto y no symlink. -- `socketPath` se restringe a `/coven.sock`. -- La ruta del socket no debe ser un symlink. -- El socket resuelto debe ser un socket Unix. -- La raíz del socket, el directorio del socket y el socket deben pertenecer al usuario actual. -- La raíz y el directorio del socket no deben ser accesibles por grupo o por todos. -- La ruta del socket se huellea alrededor de la conexión para detectar carreras de reemplazo. - -Estas comprobaciones del lado del cliente mejoran la defensa en profundidad. No reemplazan la aplicación del daemon en Rust. - -## Lo que esto no es - -La solución de auth actual no es: - -- OAuth; -- OpenID Connect; -- sesiones JWT; -- auth con bearer token; -- auth con API key; -- auth con cookies de navegador; -- RBAC; -- autorización multi-usuario; -- una política CSRF/origen; -- un límite de cuenta en la nube; ni -- permiso para exponer la API por socket en TCP local, una red remota o una página de navegador. - -Si un futuro dashboard, app móvil, puente remoto o servicio expuesto al navegador necesita hablar con Coven, necesita un diseño adicional explícito de auth y emparejamiento. No tunelices ni proxifiques el socket crudo del daemon en un servicio de red y llames a eso autenticado. - -## Brecha de hardening actual - -El cliente TypeScript del plugin OpenClaw ya realiza una validación estricta del ancla de confianza del socket. - -El daemon en Rust actualmente posee la aplicación de peticiones y el comportamiento de la API por socket, pero las comprobaciones del lado de Rust de propiedad y permisos privados de `COVEN_HOME` antes de crear, enlazar o eliminar estado del daemon siguen siendo una prioridad de hardening. Hasta que eso se implemente, la validación del socket del lado del cliente debe tratarse como defensa en profundidad para clientes cooperativos, no como un límite completo de auth del lado del daemon. - -Antes de una distribución amplia, Rust debe fallar en cerrado cuando: - -- `COVEN_HOME` no pertenece al usuario actual; -- `COVEN_HOME` es accesible por grupo o por todos; -- `COVEN_HOME` se resuelve a través de un symlink; -- la ruta del socket se resuelve fuera de `COVEN_HOME`; -- una ruta de socket existente es un symlink o un archivo no-socket; o -- la creación o limpieza del socket cruzaría el límite del directorio de estado de confianza. - -## Requisitos para nuevos clientes - -Los nuevos clientes de Coven deben: - -- usar rutas `/api/v1/...`; -- llamar a `GET /api/v1/health` antes de asumir compatibilidad; -- tratar el daemon en Rust como el límite de autoridad; -- mantener las credenciales del proveedor en el flujo de auth del proveedor o del harness; -- evitar almacenar secretos del repositorio, volcados de entorno, URLs privadas o logs portadores de tokens; -- rechazar rutas de socket configurables que no se resuelvan a `/coven.sock`; -- fallar en cerrado ante ids de harness desconocidos o versiones de API no compatibles; y -- evitar añadir cualquier transporte de red, navegador o remoto sin un diseño de auth separado. diff --git a/docs/es/CLIENT-INTEGRATION.md b/docs/es/CLIENT-INTEGRATION.md deleted file mode 100644 index c3d1bef7..00000000 --- a/docs/es/CLIENT-INTEGRATION.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: "Guía de integración de clientes" -description: "Cómo comux, OpenClaw y otros clientes deben hablar con la API por socket del daemon de Coven sin duplicar la política o autoridad del runtime." ---- - -# Guía de integración de clientes - -Coven es un sustrato de runtime. Los clientes deben presentar, enrutar y observar el trabajo sin apoderarse del límite de autoridad. - -## Regla de integración - -Habla con Coven a través de la API por socket local. No dupliques la política de ruta, harness, sesión viva o borrado de Coven de una forma que pueda divergir del daemon. - -Handshake recomendado: - -1. Llama a `GET /api/v1/health`. -2. Confirma que `apiVersion === "coven.daemon.v1"` y que los campos `capabilities` necesarios están disponibles. -3. Llama a `GET /api/v1/capabilities` si usas acciones del plano de control. -4. Usa solo rutas versionadas `/api/v1/...`. - -```mermaid -sequenceDiagram - participant Client - participant Daemon - - Client->>Daemon: GET /api/v1/health - alt daemon unreachable - Daemon--xClient: connection refused - Client->>Client: show "coven daemon start" hint - else apiVersion != coven.daemon.v1 - Daemon-->>Client: 200 { apiVersion: "coven.daemon.v2" } - Client->>Client: show "update Coven or client" hint - else compatible - Daemon-->>Client: 200 { apiVersion: "coven.daemon.v1", capabilities } - Client->>Daemon: GET /api/v1/capabilities (if using actions) - Daemon-->>Client: capability catalog - Client->>Daemon: GET /api/v1/sessions ... - Daemon-->>Client: SessionRecord[] - end -``` - -Los clientes deben tratar el handshake como **obligatorio antes de cualquier otra petición**. Saltarlo significa depender de formas de respuesta indefinidas de una versión futura del daemon. - -## Responsabilidades del cliente - -Los clientes pueden poseer: - -- la navegación; -- los paneles; -- la UI de chat o de captura; -- los formularios de tareas; -- las superficies de diff/review; -- la renderización de notificaciones; -- la selección de sesión; -- el estado optimista de UI local; y -- la UX de aprobación del usuario. - -Los clientes no deben ser el único punto de aplicación para: - -- los límites de raíz de proyecto; -- las restricciones de cwd; -- las allowlists de harness; -- las comprobaciones de sesión viva; -- las reglas de borrado destructivo; -- la confianza del socket; -- las aprobaciones de acciones externas. - -## comux - -comux es la capa de cockpit. - -Buenas responsabilidades de comux: - -- listar sesiones de Coven; -- lanzar sesiones desde el contexto visible de proyecto/worktree; -- abrir sesiones en paneles; -- adjuntar/reanudar trabajo vivo; -- leer `coven sessions --json` para descubrimiento local simple cuando el control a nivel de daemon es innecesario; -- mostrar logs y artefactos; -- ayudar a revisar diffs; -- ayudar a hacer merge, PR, archivar o limpiar explícitamente. - -comux debe seguir siendo útil cuando Coven no está instalado. Si Coven falta, presenta estados claros de instalación y fallback en lugar de asumir que el daemon existe. - -## Plugin de OpenClaw - -La integración con OpenClaw pertenece al paquete externo external OpenClaw bridge plugin, no al núcleo de OpenClaw. - -El plugin debe: - -- registrar un backend Coven opcional; -- validar la configuración para la UX; -- conectarse al socket local; -- lanzar sesiones a través de `POST /api/v1/sessions`; -- mapear eventos de Coven a eventos de runtime de OpenClaw; -- preservar el comportamiento de fallback solo cuando esté configurado explícitamente; y -- tratar el daemon en Rust como la autoridad de lanzamiento. - -El plugin no debe: - -- saltarse el daemon para los lanzamientos; -- depender de los internos del núcleo de OpenClaw; -- almacenar credenciales del proveedor; -- asumir que las rutas no versionadas son estables; ni -- ampliar los permisos de raíz de proyecto. - -## Superficies de captura - -Los clientes de chat/captura se tratan mejor como capas de captura y presentación. - -Responsabilidades útiles: - -- capturar la intención del usuario; -- mostrar el estado local; -- presentar aprobaciones; -- mostrar notificaciones; -- entregar trabajo a Coven; -- mostrar actualizaciones de sesión desde Coven. - -Evita convertir los clientes de captura en el motor de automatización. La automatización reutilizable debe vivir detrás de capabilities y acciones de Coven para que el límite de política permanezca centralizado. - -## Clientes de escritorio y salas de control - -Una sala de control nativa puede facilitar el manejo de Coven mostrando: - -- sesiones activas; -- sesiones archivadas; -- salud del daemon; -- raíces de proyecto; -- disponibilidad de harness; -- integraciones de cliente; -- catálogo de capabilities; -- cola de aprobación de acciones; -- logs y trazas; -- enlaces a docs y troubleshooting. - -Usa `coven sessions --json` para sesiones activas y `coven sessions --json --all` cuando el cliente también necesite registros archivados. La CLI devuelve un objeto de nivel superior con un array `sessions`, y cada registro usa los mismos nombres de campo `SessionRecord` expuestos por la API del daemon, incluidos `project_root`, `status`, `created_at`, `updated_at` y el `archived_at` anulable. - -La sala de control debe seguir usando la misma API por socket y el mismo handshake de capabilities que los demás clientes. - -## Adaptadores de automatización de escritorio - -La automatización de escritorio es útil cuando una app no tiene una API limpia. También es lo suficientemente potente como para necesitar una política clara. - -Patrón recomendado: - -```text -user request - -> client captures intent - -> Coven exposes capability and policy hints - -> client asks for approval when required - -> Coven routes a known action id - -> adapter performs the local UI action - -> event/result returns to the client -``` - -No dejes que los clientes de UI se enlacen directamente con librerías de automatización del SO y luego llamen a eso "integración de Coven". El límite reutilizable debe ser el plano de control de Coven. - -## Expectativas de compatibilidad - -Para cada integración: - -- usa `/api/v1`; -- llama a health primero; -- ignora los campos aditivos desconocidos cuando sea seguro; -- falla en cerrado ante comportamiento requerido desconocido; -- prueba contra respuestas representativas del daemon; -- actualiza `docs/API-CONTRACT.md` cuando cambien las formas de respuesta. - -## Manejo de errores - -Un buen cliente debe traducir los errores del daemon en UI orientada a la acción: - -- daemon no disponible: muestra instrucciones de inicio/reinicio; -- versión de API no compatible: pide al usuario que actualice Coven o el cliente; -- harness faltante: muestra la guía de `coven doctor`; -- cwd fuera de raíz: explica el límite del proyecto; -- sesión no viva: ofrece visualización del log en lugar de input en vivo; -- acción destructiva bloqueada: explica que la sesión está en ejecución o le falta confirmación. diff --git a/docs/es/COMUX-DEMO-LOOP.md b/docs/es/COMUX-DEMO-LOOP.md deleted file mode 100644 index 24a7f03e..00000000 --- a/docs/es/COMUX-DEMO-LOOP.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Bucle de demo de comux y Coven" -description: "Contrato de Coven para exponer sesiones de Codex y Claude Code como paneles descubribles desde comux mediante la API por socket local." ---- - -# Bucle de demo comux + Coven - -Este es el contrato del lado de Coven para hacer visibles en comux las sesiones de Codex y Claude Code gestionadas por Coven. - -```mermaid -flowchart LR - subgraph Dev["Developer"] - Open[Open repo in comux] - end - - subgraph Local["Local machine"] - Comux[comux cockpit] - CLI[coven CLI] - Daemon[Coven daemon] - PTY1[Codex PTY] - PTY2[Claude PTY] - Store[(SQLite store + events)] - end - - Open --> Comux - Comux -->|discover| CLI - CLI -->|coven sessions --json| Daemon - Daemon --> Store - Daemon --> PTY1 - Daemon --> PTY2 - Comux -->|open / attach| Daemon - Daemon -->|/events| Comux - Comux --> Review[Inspect · Diff · Merge · PR] - Review --> Ritual[Archive · Summon · Sacrifice] - Ritual --> Daemon -``` - -El bucle de demo es extremo a extremo: comux nunca se salta el daemon, y el daemon nunca confía en comux para la aplicación de raíz de proyecto, harness o borrado destructivo. - -## Bucle - -1. Abre el repositorio objetivo en comux. -2. Arranca Coven si es necesario: - - ```sh - coven daemon start - ``` - -3. Lanza una sesión respaldada por Coven desde el mismo repositorio: - - ```sh - coven run codex "fix the failing tests" - coven run claude "review the diff" - ``` - -4. Deja que comux descubra sesiones a través de cualquiera de las rutas de cliente soportadas: - - `coven sessions --json` para descubrimiento local simple por CLI. - - `GET /api/v1/sessions` después de `GET /api/v1/health` para clientes del daemon. -5. Abre la sesión como un panel visible de comux, o adjúntate manualmente: - - ```sh - coven attach - ``` - -6. Inspecciona archivos, diffs y la salida de la sesión desde comux. -7. Haz merge, crea un PR, archiva, invoca, sacrifica o limpia explícitamente tras la verificación. - -## Descubrimiento por CLI - -`coven sessions --json` imprime un objeto estable con un array `sessions`. Los registros usan los mismos nombres snake_case que la API del daemon: - -```json -{ - "sessions": [ - { - "id": "session-1", - "project_root": "/repo", - "harness": "codex", - "title": "Fix the tests", - "status": "running", - "exit_code": null, - "archived_at": null, - "created_at": "2026-05-14T07:00:00Z", - "updated_at": "2026-05-14T07:00:01Z" - } - ] -} -``` - -Usa `--all --json` cuando las sesiones archivadas también deban ser visibles. - -## Descubrimiento por daemon - -Los clientes del daemon deben usar la API por socket versionada: - -1. `GET /api/v1/health` -2. Verifica `apiVersion === "coven.daemon.v1"` y `capabilities.sessions === true`. -3. `GET /api/v1/sessions` -4. Filtra las sesiones por raíz de proyecto verificada antes de mostrarlas en una UI limitada al proyecto. - -El socket del daemon usa por defecto `~/.coven/coven.sock`. El daemon sigue siendo la autoridad para raíces de proyecto, cwd, ids de harness, comprobaciones de sesión viva, input, peticiones de kill, estado de archivo y reglas de borrado destructivo. - -## Estados no disponibles - -Los clientes deben mantener su UI principal usable cuando Coven falta o está detenido: - -- CLI faltante: muestra la guía de instalación para `@opencoven/cli`. -- Daemon detenido o socket faltante: sugiere `coven daemon start`. -- Harness faltante: sugiere `coven doctor`. -- Versión de API no compatible: pide al usuario que actualice Coven o el cliente. - -## Roadmap - -El roadmap más amplio de OpenCoven sigue siendo el punto de seguimiento público para la demo extremo a extremo: [ROADMAP.md](/ROADMAP). diff --git a/docs/es/CONCEPTS.md b/docs/es/CONCEPTS.md deleted file mode 100644 index 69869872..00000000 --- a/docs/es/CONCEPTS.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Conceptos y terminología de Coven" -description: "Definiciones de los sustantivos que Coven usa en la CLI, el daemon, la API y los clientes: harnesses, sesiones, proyectos, rituales, summon y sacrifice." ---- - -# Conceptos de Coven - -Esta página define los sustantivos usados en la CLI, el daemon, la API, los docs y las integraciones de clientes de Coven. - -```mermaid -flowchart TB - OpenCoven[OpenCoven ecosystem] --> Coven[Coven runtime] - Coven --> Daemon[Daemon] - Daemon --> Project[Project root] - Daemon --> Cwd[Working directory] - Daemon --> Harness[Harness] - Daemon --> Session[Session] - Session --> Event[Event] - Daemon --> Store[Store / SQLite] - Daemon --> Socket[Socket API /api/v1] - Socket --> ControlPlane[Control plane] - ControlPlane --> Capability[Capability] - Socket --> Client[Client] - Session --> Ritual["Rituals: archive / summon / sacrifice"] -``` - -Cada término abajo es un nodo del grafo anterior. - -## OpenCoven - -OpenCoven es el ecosistema y la organización alrededor del runtime, el cockpit y las integraciones. - -Usa **OpenCoven** al hablar de la familia más amplia del proyecto. - -## Coven - -Coven es el sustrato de runtime local. Posee las sesiones de harness limitadas al proyecto, los PTYs, los logs, el estado del daemon local y la API por socket. - -Usa **Coven** para la CLI, el daemon, el crate de Rust, el wrapper de npm y el runtime de sesión local. - -## `coven` - -`coven` es el comando orientado al usuario. - -No le digas a los usuarios que ejecuten `opencoven` o `@opencoven`. Los nombres de paquete viven bajo `@opencoven/*`, pero el comando es siempre `coven`. - -## Harness - -Un harness es una CLI externa de agente de codificación que Coven puede lanzar y supervisar. - -Harnesses v0 actuales: - -- Codex, con id de harness `codex`. -- Claude Code, con id de harness `claude`. - -Coven no almacena credenciales del proveedor. Cada harness sigue usando su propio flujo local de autenticación. - -## Raíz de proyecto - -La raíz de proyecto es el límite explícito para una sesión. Coven valida y canonicaliza la raíz de proyecto antes de lanzar trabajo. - -La raíz importa porque define dónde se permite al harness arrancar. Un cliente no puede ampliar este límite enviando un `cwd` distinto o un valor de configuración más laxo. - -## Directorio de trabajo - -El directorio de trabajo es el directorio de lanzamiento de una sesión de harness. Debe estar dentro de la raíz de proyecto tras la canonicalización. - -Ejemplos: - -```sh -coven run codex "fix tests" -coven run codex "inspect the CLI package" --cwd packages/cli -``` - -El segundo comando es válido solo cuando `packages/cli` se resuelve dentro de la raíz de proyecto seleccionada. - -## Sesión - -Una sesión es un registro propiedad de Coven de una ejecución de harness. - -Incluye: - -- un id de sesión estable; -- raíz de proyecto; -- id de harness; -- título legible; -- estado; -- código de salida opcional; -- estado de archivo; y -- timestamps de creación/actualización. - -Los registros de sesión se almacenan en SQLite. - -## Evento - -Un evento es un registro append-only asociado a una sesión. - -Los eventos incluyen registros de salida, salida del proceso y metadatos. Permiten a los clientes reproducir o inspeccionar lo que pasó después de que el proceso saliera o el daemon se reiniciara. - -## Daemon - -El daemon es el proceso local de Rust que posee el estado de sesión viva y expone la API HTTP-sobre-socket-Unix. - -El daemon es el límite de autoridad. Valida: - -- las peticiones de lanzamiento; -- las raíces de proyecto; -- los directorios de trabajo; -- los ids de harness; -- el input en vivo; -- las peticiones de kill; y -- los ids de sesión. - -## Almacén - -El almacén es la base de datos SQLite local de Coven. Contiene metadatos de sesión y el historial append-only de eventos. - -El estado de runtime queda fuera del control de fuente. No hagas commit de `.coven/`, bases de datos, sockets, logs ni archivos de entorno. - -## Cliente - -Un cliente es cualquier cosa que habla con Coven en lugar de lanzar harnesses directamente. - -Formas de cliente conocidas: - -- CLI/TUI `coven`. -- Cockpit comux. -- Paquete externo del plugin OpenClaw external OpenClaw bridge plugin. -- Futura superficie de captura o de escritorio. - -Los clientes son capas de conveniencia, no raíces de confianza. - -## Plano de control - -El plano de control es la capa de capabilities y enrutamiento de acciones por delante de los futuros adaptadores. - -Permite a los clientes descubrir lo que Coven puede hacer mediante `GET /api/v1/capabilities` y enviar acciones conocidas mediante `POST /api/v1/actions`. Los ids de acción desconocidos fallan en cerrado. - -## Capability - -Una capability describe una funcionalidad propiedad del daemon o del adaptador que un cliente puede presentar. - -Los registros de capability incluyen: - -- id; -- etiqueta; -- adaptador propietario; -- estado; -- pista de política; y -- ids de acción. - -## Rituales - -Los rituales son los verbos amigables para humanos de gestión de sesiones de Coven: - -- **Archive** oculta una sesión completada de la lista activa preservando los eventos. -- **Summon** restaura una sesión archivada. -- **Sacrifice** borra permanentemente una sesión no en ejecución y sus eventos. - -Los nombres de los rituales son lenguaje de producto. El comportamiento de seguridad subyacente debe seguir siendo preciso y conservador. - -## API por socket - -La API por socket es el límite público de compatibilidad para clientes locales. - -Prefijo estable actual: - -```text -/api/v1 -``` - -Los clientes deben hacer handshake con: - -```text -GET /api/v1/health -``` - -antes de depender de otras formas de respuesta. diff --git a/docs/es/GETTING-STARTED.md b/docs/es/GETTING-STARTED.md deleted file mode 100644 index 914a49a6..00000000 --- a/docs/es/GETTING-STARTED.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Empieza con Coven" -description: "Instala Coven, lanza tu primera sesión de Codex o Claude Code limitada al proyecto y verifica el daemon, el almacén y los harnesses con coven doctor." ---- - -# Empieza con Coven - -Esta guía lleva a un nuevo usuario desde un checkout fresco o instalación con npm hasta una sesión de agente visible limitada al proyecto. - -## Qué es Coven - -Coven es un runtime local-first para harnesses de agentes de codificación. Ejecuta CLIs soportadas como Codex y Claude Code dentro de límites explícitos de proyecto, registra metadatos y eventos de sesión, y expone el trabajo a través de una CLI, una TUI y una API por socket local. - -La promesa corta: - -> Un proyecto. Cualquier harness. Trabajo visible. - -## Rutas de instalación - -Usa el wrapper de npm cuando quieras la instalación pública más rápida: - -```sh -npx @opencoven/cli doctor -pnpm dlx @opencoven/cli doctor -``` - -Compila desde fuente cuando estés contribuyendo a Coven: - -```sh -git clone https://github.com/OpenCoven/coven.git -cd coven -cargo build --workspace -cargo run -p coven-cli -- doctor -``` - -## Prerrequisitos - -Coven necesita: - -- Rust stable, si se compila desde fuente. -- Git. -- Un runtime local tipo Unix para la ruta actual del socket del daemon y del PTY. -- Al menos una CLI de harness compatible en `PATH`. - -Harnesses v0 compatibles: - -- `codex` -- `claude` - -Instala y autentica un harness antes de esperar que `coven run` funcione: - -```sh -npm install -g @openai/codex -codex login - -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -## Primera ejecución - -Desde un directorio de proyecto: - -```sh -coven -``` - -El comando por defecto abre la TUI prompt-first. Puedes: - -- escribir una tarea directamente y pulsar Enter (p. ej. `fix the failing tests` o un comando slash como `/run codex fix the failing tests`); -- seleccionar un elemento del menú con las flechas o su atajo de una sola tecla y pulsar Enter; -- pulsar `h` o escribir `/help` para ver ejemplos de lenguaje natural y comandos slash; -- pulsar `Ctrl+C` o `Esc` para salir. - -Si prefieres ejecutar las comprobaciones de configuración explícitas: - -```sh -coven doctor -``` - -`coven doctor` comprueba: - -- la preparación del almacén; -- la detección del proyecto; -- la disponibilidad del harness incorporado; y -- los siguientes pasos para configuración faltante. - -## Ejecuta una sesión - -Arranca el daemon y luego lanza una sesión de harness desde un repositorio o directorio de proyecto: - -```sh -coven daemon start -coven run codex "fix the failing tests" -``` - -o: - -```sh -coven run claude "polish the CLI help text" -``` - -Para una lista de sesiones más legible, pasa un título: - -```sh -coven run codex "update the docs" --title "Docs refresh" -``` - -Usa un directorio de trabajo específico solo cuando esté dentro de la raíz de proyecto detectada: - -```sh -coven run codex "inspect this package" --cwd packages/cli -``` - -Coven rechaza directorios de trabajo fuera de la raíz. Los clientes pueden validar para una mejor UX, pero el daemon en Rust es la autoridad. - -## Explorar sesiones - -En un terminal interactivo: - -```sh -coven sessions -``` - -Esto abre el explorador de sesiones. Puedes seleccionar una sesión y elegir acciones contextuales: - -- **Rejoin** para sesiones vivas. -- **View Log** para sesiones completadas. -- **Summon** para sesiones archivadas. -- **Archive** para sesiones completadas visibles. -- **Sacrifice** para borrado permanente de sesiones y eventos no en ejecución. - -Para scripts o flujos de copiar/pegar: - -```sh -coven sessions --plain -coven sessions --all --plain -coven sessions --json -coven sessions --json --all -``` - -## Attach, archive, summon y sacrifice - -Los verbos de sesión de bajo nivel siguen disponibles: - -```sh -coven attach -coven archive -coven summon -coven sacrifice --yes -``` - -Archive es reversible. Summon restaura una sesión archivada a la lista activa. Sacrifice es destructivo y rechaza sesiones vivas. - -## Detén el daemon - -```sh -coven daemon stop -``` - -Usa `restart` cuando el socket o el estado del daemon parezcan obsoletos: - -```sh -coven daemon restart -``` - -## Diagnósticos y relief - -`coven pc` es una herramienta de diagnóstico y relief del sistema, primero para macOS, expuesta a través de la CLI de Coven. Todas las operaciones de lectura son libres de efectos secundarios. - -Inspecciona: - -```sh -coven pc # full report: CPU, memory, disk, top processes -coven pc status # one-line health summary with 🟢/🟡/🔴 indicators -coven pc status --json # machine-readable health summary -coven pc top --n 10 # top-N processes by CPU usage -coven pc disk # disk usage breakdown -``` - -Las operaciones de relief mutan el estado del sistema y requieren una puerta explícita `--confirm`: - -```sh -coven pc kill --confirm # SIGTERM with PID identity re-check -coven pc cache clear --confirm # clear ~/Library/Caches + /Library/Caches -``` - -Restricciones de seguridad en v1: - -- Todas las operaciones de escritura requieren `--confirm`. No hay ruta de bypass. -- La terminación es solo SIGTERM. Nada de SIGKILL. -- La identidad del proceso se reverifica justo antes de SIGTERM para prevenir reutilización de PID. -- El borrado de caché usa una lista de rutas codificadas. Sin expansión de glob. -- Los argumentos del proceso se redactan por defecto; pasa `--verbose` para inspeccionarlos. -- Sin `sudo`, sin mutación de LaunchAgent, sin control de servicios del sistema. - -## Flujo extremo a extremo - -```mermaid -flowchart LR - Install["Install\nnpx @opencoven/cli doctor"] --> Doctor["coven doctor"] - Doctor --> Daemon["coven daemon start"] - Daemon --> Run["coven run codex prompt"] - Run --> Sessions["coven sessions\n(rejoin / view log / archive)"] - Sessions --> Sacrifice["coven sacrifice id --yes\n(when done)"] - - Doctor -. on failure .-> Harness["Install harness CLI\n+ provider login"] - Harness --> Doctor -``` - -El bucle "install → doctor → daemon → run → sessions" es todo el camino feliz para una primera sesión. Todo lo demás en esta guía es fallback o troubleshooting. - - -## Bucle de verificación del contribuidor - -Antes de abrir un PR: - -```sh -cargo fmt --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace --locked -python scripts/check-secrets.py -``` - -Para cambios de daemon/sesión, ejecuta también el smoke test: - -```sh -cargo test -p coven-cli --test smoke -- --nocapture -``` - -El smoke test usa un `COVEN_HOME` temporal y un ejecutable de harness falso. No requiere credenciales privadas de harness. diff --git a/docs/es/GLOSSARY.md b/docs/es/GLOSSARY.md deleted file mode 100644 index 2de26dfd..00000000 --- a/docs/es/GLOSSARY.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Glosario de Coven" -description: "Definiciones para términos de Coven: ACP, versión de API, archive, capability, cliente, comux, harness, raíz de proyecto, ritual, sacrifice, sesión y summon." ---- - -# Glosario - -Cómo encajan los términos a primera vista: - -```mermaid -flowchart LR - OpenCoven[OpenCoven] --> Coven[Coven] - Coven --> CLI[coven CLI / TUI] - Coven --> Daemon[Daemon] - Daemon --> Store[Store / SQLite] - Daemon --> SocketAPI[Socket API] - Daemon --> ControlPlane[Control plane] - ControlPlane --> Capability[Capability] - Daemon --> Harness[Harness] - Harness --> PTY[PTY] - Harness -.->|owns auth| Provider((Provider)) - Daemon --> Session[Session] - Session --> Event[Event] - Session --> Ritual[Rituals: archive / summon / sacrifice] - Client[Client] --> SocketAPI - Client --> Comux[comux] - Client --> Plugin["OpenClaw bridge (OpenClaw plugin)"] -``` - -Las definiciones siguen en orden alfabético. - - -## ACP - -Agent Client Protocol. En este repo, ACP aparece como una superficie de integración para runtimes de agentes externos y compatibilidad con OpenClaw. Coven en sí no es una implementación de ACP; el plugin externo de OpenClaw mapea entre eventos de runtime de OpenClaw y sesiones de Coven. - -## Versión de API - -El contrato de compatibilidad nombrado expuesto por la API por socket del daemon. Valor estable actual: `coven.daemon.v1`. - -## Archive - -Ocultar una sesión no en ejecución de la lista activa preservando su registro y eventos. - -## Capability - -Una funcionalidad del daemon o del adaptador descubrible devuelta por `GET /api/v1/capabilities`. - -## Cliente - -Cualquier proceso o UI que habla con el daemon de Coven, incluida la CLI, comux o el plugin de OpenClaw. - -## comux - -La capa de cockpit para trabajo visible de agente, paneles, worktrees, revisión y flujo de merge. comux puede consumir sesiones de Coven pero no es el runtime de Coven. - -## Plano de control - -La capa del daemon que expone capabilities y enruta ids de acción conocidos a los adaptadores que posee. - -## Coven - -El sustrato de runtime local de OpenCoven y el producto de línea de comandos. - -## `coven` - -El comando orientado al usuario. - -## `coven pc` - -Subcomando de diagnóstico y relief del sistema, primero para macOS. Informa de CPU, memoria, disco y procesos top. Las operaciones de escritura (kill de proceso, borrado de caché) están protegidas por `--confirm`. - -## `COVEN_HOME` - -El directorio local donde Coven almacena el estado de daemon/socket/base de datos cuando está configurado. El estado de runtime no debe hacerse commit al control de fuente. - -## Daemon - -El proceso local en Rust que posee el estado de sesión viva y la API por socket. - -## Evento - -Un registro append-only para salida, salida del proceso o metadatos de la sesión. - -## Harness - -Una CLI de agente de codificación compatible que Coven puede lanzar y supervisar. - -## OpenCoven - -El ecosistema y organización más amplios alrededor de Coven, comux y las integraciones relacionadas. - -## Plugin de OpenClaw - -El paquete externo external OpenClaw bridge plugin, que permite a OpenClaw usar Coven mediante la API por socket. No forma parte del núcleo de OpenClaw. - -## Raíz de proyecto - -El límite explícito de repositorio o proyecto para una sesión. - -## PTY - -Pseudoterminal. Coven usa PTYs para que los harnesses se comporten como herramientas nativas de terminal mientras su salida puede seguir registrándose y reproduciéndose. - -## TUI prompt-first - -La interfaz por defecto de `coven` y `coven tui`. Acepta texto de tarea libre o comandos slash como `/run codex ` como input, junto con navegación por menús con teclas de flecha. - -## Relief - -Operaciones del lado de escritura en `coven pc` que mutan el estado del sistema (terminación de procesos, borrado de caché). Siempre requieren una flag `--confirm` explícita. - -## Sacrifice - -Borrar permanentemente una sesión no en ejecución y sus eventos. - -## Sesión - -Un registro propiedad de Coven de una ejecución de harness. - -## API por socket - -La API HTTP-sobre-socket-Unix local expuesta por el daemon. - -## Summon - -Restaurar una sesión archivada a la lista activa y luego reproducirla/seguirla. - -## Coordinación futura - -El handoff multi-harness y el enrutamiento de tareas no son funciones públicas actuales de la CLI/API. Deben documentarse solo como trabajo de roadmap hasta que se implementen. diff --git a/docs/es/HARNESS-ADAPTERS.md b/docs/es/HARNESS-ADAPTERS.md deleted file mode 100644 index 93957f02..00000000 --- a/docs/es/HARNESS-ADAPTERS.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Guía de adaptadores de harness" -description: "La forma del adaptador de harness que Coven usa hoy, la barra para añadir nuevos harnesses y cómo Codex, Claude Code y GitHub Copilot CLI se mapean a la superficie de adaptador v0." ---- - -# Guía de adaptadores de harness - -Coven soporta Codex, Claude Code y GitHub Copilot CLI. Esta guía describe la forma actual del adaptador y la barra para añadir más harnesses. - -## Forma actual del adaptador - -Un adaptador de harness incorporado define: - -- id de harness estable de Coven; -- etiqueta orientada al usuario; -- nombre de ejecutable a detectar en `PATH`; -- forma del argumento de prompt para modo interactivo; -- forma del argumento de prompt para modo no interactivo; y -- pista de instalación/autenticación para `coven doctor`. - -La implementación actual espera que el prompt sea el último argumento del comando tras cualquier args de prefijo fijo. - -## Harnesses incorporados - -### Codex - -- Id de harness: `codex` -- Ejecutable: `codex` -- Args de prefijo interactivo: ninguno -- Args de prefijo no interactivo: `exec --skip-git-repo-check --color never` - -Pista de configuración: - -```sh -npm install -g @openai/codex -codex login -``` - -### Claude Code - -- Id de harness: `claude` -- Ejecutable: `claude` -- Args de prefijo interactivo: ninguno -- Args de prefijo no interactivo: `--print` - -Pista de configuración: - -```sh -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -## Requisitos del adaptador - -Antes de añadir un nuevo harness, confirma: - -- la CLI puede detectarse de forma segura en `PATH`; -- el prompt puede pasarse sin interpolación por shell; -- el proceso puede ejecutarse desde un cwd validado del proyecto; -- la salida puede capturarse mediante eventos de PTY/sesión; -- la autenticación se queda en el flujo local normal del proveedor del harness; -- los modos de fallo son comprensibles en `coven doctor`; -- los tests cubren la construcción del comando y el comportamiento ante ejecutable faltante. - -## Lo que aún no debes añadir - -Evita adaptadores genéricos de comando arbitrario hasta que Coven tenga política explícita y comportamiento de aprobación para ellos. - -Los comandos arbitrarios son más peligrosos que los adaptadores de harness con nombre porque pueden difuminar la diferencia entre "ejecutar un agente de codificación en este proyecto" y "ejecutar cualquier string que un cliente envió". Mantén v0 estrecho. - -## Lista de evaluación para futuros harnesses - -Para un harness candidato, documenta: - -- comando de instalación; -- nombre del ejecutable; -- flujo de auth local; -- comando de prompt único; -- comando interactivo; -- comando de reanudación/sesión, si existe; -- modo de salida no interactivo; -- si se necesita inyectar el prompt por stdin; -- si la CLI puede deshabilitar color/secuencias de control; -- si la CLI puede evitar riesgos de quoting de shell; -- códigos de salida conocidos; -- smoke test mínimo seguro. - -## Mapeo de identidad de sesión - -Algunos harnesses tienen sus propios ids de sesión upstream. El id de sesión de Coven sigue siendo el id del runtime local. - -Si los ids upstream se vuelven útiles, almacénalos como metadatos en lugar de reemplazar el id propio de Coven. Los clientes deben poder confiar en un id estable de Coven para attach, eventos, archive, summon y sacrifice. - -## Etapas de madurez sugeridas para el adaptador - -1. **Nota de investigación** - documenta la forma de la CLI y los riesgos. -2. **Tests de construcción de comando** - prueba que la construcción de argv es segura. -3. **Detección por doctor** - añade pistas de instalación/auth. -4. **Smoke de lanzamiento** - prueba que una sesión puede ejecutarse en un proyecto temporal. -5. **Smoke de attach/replay** - prueba que los eventos pueden reproducirse. -6. **Compatibilidad de clientes** - actualiza docs y tests de integración. - -No saltes de la investigación directamente al soporte público. - -```mermaid -flowchart LR - S1["1. Research note\n(public CLI shape + risks)"] --> S2 - S2["2. argv construction tests\n(no shell, prompt last)"] --> S3 - S3["3. coven doctor detection\n(install + auth hints)"] --> S4 - S4["4. Launch smoke\n(temp project, fake creds)"] --> S5 - S5["5. Attach / replay smoke\n(events round-trip)"] --> S6 - S6["6. Client compatibility\n(comux + plugin tests)"] --> Done(["Public support"]) - - style S1 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S2 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S3 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S4 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S5 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S6 fill:#3D3547,stroke:#9A8ECD,color:#fff - style Done fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 -``` - -Un harness que se salte cualquier etapa **no** está listo para soporte público, incluso si parece funcionar en la máquina de un mantenedor. diff --git a/docs/es/PRODUCT-SPEC.md b/docs/es/PRODUCT-SPEC.md deleted file mode 100644 index 55d3ec4a..00000000 --- a/docs/es/PRODUCT-SPEC.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Spec de producto de Coven" -description: "Tesis de producto, alcance MVP, dirección de harness, superficie CLI/TUI y API del daemon del runtime local de agentes Coven y su integración con OpenClaw." ---- - -# Spec de producto de Coven - -## Tesis de producto - -Coven es un sustrato de harness primero en Rust para ejecutar agentes de codificación como sesiones limitadas al proyecto, observables y adjuntables. Permite a los desarrolladores traer los harnesses en los que ya confían a un runtime local controlado en lugar de forzar a un único proveedor de agente o UI. - -Estrella polar: **Un proyecto. Cualquier harness. Trabajo visible.** - -## Alcance MVP - -El MVP demuestra el bucle de runtime central: - -- Un binario CLI independiente llamado `coven` -- Un daemon local para sesiones supervisadas -- Límites explícitos de raíz de proyecto -- Ejecución interactiva de sesiones por PTY -- Persistencia de metadatos y eventos de sesión -- Comandos y flujos TUI para ejecutar, navegar, reanudar, ver, archivar, invocar, sacrificar y matar sesiones vivas a través de la API del daemon -- Una API local mínima para clientes de primera parte -- Un paquete de plugin externo de OpenClaw que consume esa API sin entrar en el núcleo de OpenClaw -- Distribución pública y documentación para early adopters - -Fuera del alcance del MVP: plugins de marketplace, sincronización en la nube, colaboración multi-usuario, una reescritura completa de comux, integración bundled con el núcleo de OpenClaw o reemplazo de OpenClaw. - -## Dirección de harness incorporado v0 - -Coven v0 debe entregarse con adaptadores incorporados para Codex y Claude Code. Estos adaptadores deben detectar la disponibilidad local de la CLI, construir comandos sin interpolación por shell donde sea posible, ejecutar el harness dentro de un `cwd` validado del proyecto y exponer salida/input a través de sesiones PTY gestionadas por Coven. - -La UX de terminal debe seguir centrada en el comando ligero `coven` y un explorador humano de sesiones: - -```sh -coven -coven tui -coven run codex "fix tests" -coven run claude "polish this UI" -coven sessions -coven sessions --plain -``` - -En un terminal interactivo, `coven sessions` abre un explorador con acciones legibles como **Rejoin**, **View Log**, **Summon**, **Archive** y **Sacrifice** para que los usuarios no tengan que memorizar ids de sesión. La salida en texto plano sigue disponible para scripts y pipes. - -## Futura ruta de Hermes y de adaptador - -Hermes y otros harnesses deben llegar mediante un pequeño contrato de adaptador después de que la ruta v0 incorporada sea estable. El modelo de adaptador debe soportar futuros objetivos como Hermes, Aider, Gemini, OpenCode y adaptadores de comando personalizados sin requerir que Coven se convierta en un marketplace de plugins completo en el MVP. - -## Arquitectura actual - -```mermaid -flowchart LR - User[Developer] --> CLI[coven CLI / TUI] - CLI --> Daemon[Coven Rust daemon] - Comux[comux] --> Daemon - OpenClaw[OpenClaw] --> Plugin[external OpenClaw bridge plugin] - Plugin --> Daemon - Daemon --> Store[(SQLite session ledger)] - Daemon --> Router[Codex / Claude adapter router] - Router --> PTY[Harness PTYs] -``` - -Para diagramas más completos, consulta [Diagramas de arquitectura](/ARCHITECTURE). - -## Relación con comux y OpenClaw - -Coven es el sustrato de runtime local. comux puede convertirse en el cockpit visual para paneles e historial de sesión gestionados por Coven. OpenClaw puede delegar los lanzamientos de harness limitados al proyecto a Coven solo a través del plugin externo external OpenClaw bridge plugin, no a través de código bundled del núcleo de OpenClaw. El cliente de chat/captura puede consumir el estado de sesión, la captura o las notificaciones de Coven donde sea útil. - -Coven debe integrarse con estos proyectos sin ser propiedad de ninguno: es la habitación compartida donde se ejecutan los harnesses, no toda la UI ni el orquestador. - -## Límite del plugin externo de OpenClaw - -La integración con OpenClaw se externaliza. El repo de OpenClaw no debe incluir código de OpenCoven o Coven, y Coven no debe depender de los internos de OpenClaw. - -El paquete external OpenClaw bridge plugin es un adaptador de compatibilidad: - -- Las llamadas de runtime ACP de OpenClaw entran al plugin. -- El plugin valida la configuración y se conecta al socket local de Coven. -- El daemon en Rust revalida raíces de proyecto, cwd, ids de harness, input y peticiones de kill. -- Coven lanza y supervisa el PTY del harness. -- El plugin mapea eventos de Coven de vuelta a eventos de runtime ACP de OpenClaw. - -Esto hace de la API por socket el contrato. El versionado del protocolo, los tests de compatibilidad y las notas de release pertenecen al repo de Coven y al paquete del plugin, no al núcleo de OpenClaw. - -## Estado público desde el inicio - -Coven es público ahora mientras el modelo de seguridad, el comportamiento del daemon, los contratos de adaptador y la experiencia de usuario continúan madurando. El empaquetado público debe seguir siendo conservador, y la disposición debe juzgarse por si los early adopters pueden ejecutar de forma fiable Codex y Claude Code en sesiones visibles, adjuntables y limitadas al proyecto. - -## Alcance MVP de un vistazo - -```mermaid -flowchart TB - subgraph InScope["In scope for MVP"] - direction TB - Cli["coven CLI / TUI"] - Doc["coven doctor"] - DaemonOps["Daemon lifecycle"] - PrjGuard["Project-root + cwd guard"] - Codex["Codex adapter"] - Claude["Claude Code adapter"] - Pty["PTY sessions"] - Store["SQLite session ledger + events"] - Rituals["Archive / Summon / Sacrifice"] - Api["/api/v1 socket API"] - Plugin["External OpenClaw bridge plugin"] - Docs["Public docs and distribution"] - end - - subgraph OutOfScope["Out of scope for MVP"] - direction TB - Marketplace["Marketplace plugins"] - Cloud["Cloud sync"] - Multi["Multi-user collaboration"] - Rewrite["Full comux rewrite"] - Bundled["Bundled OpenClaw core integration"] - Replace["Replacing OpenClaw"] - end - - InScope -. revisit after MVP .-> OutOfScope -``` - -El límite anterior es normativo para v0. Cualquier cosa en **OutOfScope** se registra en el roadmap, no se construye en el sustrato de runtime. - -## Handles canónicos de la comunidad - -Usa estos handles/enlaces públicos exactos cuando los docs o metadatos del paquete de Coven mencionen canales de la comunidad: - -- Discord: `discord.gg/opencoven` -- X / Twitter: `@OpenCvn` diff --git a/docs/es/ROADMAP.md b/docs/es/ROADMAP.md deleted file mode 100644 index 372ac2e2..00000000 --- a/docs/es/ROADMAP.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: "Roadmap público de OpenCoven" -description: "El roadmap público de OpenCoven para Coven, comux y las integraciones de OpenClaw, con secciones shipped, now, next y later para el runtime local de agentes." ---- - -# Roadmap público de OpenCoven - -_Última actualización: 2026-05-09_ - -Este roadmap es el ledger público de progreso para **OpenCoven**, **Coven** y **comux**. - -Está escrito intencionalmente como un mapa orientado a la comunidad, no como una hoja de promesas internas. Los elementos se mueven cuando se diseñan, implementan, prueban, publican o se cortan deliberadamente. Se evitan las fechas a menos que un release ya esté programado. - -## Estrella polar - -OpenCoven está construyendo un workspace de agentes local-first donde harnesses autónomos de codificación pueden trabajar dentro de habitaciones explícitas: - -- **Coven** es el sustrato de runtime: sesiones de harness limitadas al proyecto, PTYs, logs y APIs locales. -- **comux** es el cockpit: paneles visibles, worktrees, carriles de agente, rituales, revisión y flujo de merge. -- **Las superficies de captura y la integración con OpenClaw** son superficies de captura y orquestación que pueden entregar trabajo al mismo runtime local sin ocultar lo que pasó. - -La promesa simple: - -> Un proyecto. Cualquier harness. Trabajo visible. - -## Cómo leer este roadmap - -- **Shipped** significa que el trabajo existe en código público o en artefactos públicos de paquete/release. -- **Now** significa estabilización activa o implementación a corto plazo. -- **Next** significa planificado después de la sección actual de estabilización. -- **Later** significa direccionalmente importante, pero no se le permite distraer del MVP local-first. -- **Lab** significa trabajo experimental que estamos explorando en público cuando es posible, pero sin tratarlo todavía como una promesa estable. - -## Instantánea actual - -### Coven - -**Estado:** MVP público temprano, usable por desarrolladores aventureros local-first. - -Shipped: - -- Repo público `OpenCoven/coven`. -- Comando CLI en Rust llamado `coven`. -- Entrypoint amigable para principiantes `coven` / `coven tui`. -- Comprobaciones de configuración `coven doctor`. -- Ciclo de vida del daemon local: `coven daemon start/status/restart/stop`. -- Guardia de límite de raíz de proyecto y cwd. -- Adaptadores incorporados de harness Codex y Claude Code. -- Sesiones `coven run codex|claude ` respaldadas por PTY. -- Metadatos de sesión y log de eventos respaldados por SQLite. -- Explorador de sesiones y rituales: **Rejoin**, **View Log**, **Summon**, **Archive**, **Sacrifice**. -- Salida de sesión scriptable y humana: `coven sessions`, `--plain` y `--all`. -- API HTTP-sobre-socket-Unix local para clientes. -- Contrato versionado de API `coven.daemon.v1` con apiVersion nombrada, capabilities legibles por máquina, errores estructurados y cursores de eventos monótonos. Consulta [`docs/API-CONTRACT.md`](/API-CONTRACT). -- Tests de compatibilidad para el puente externo de OpenClaw contra respuestas versionadas del daemon. -- Pistas de recuperación de primera ejecución para CLIs de Codex o Claude Code faltantes. -- Cobertura real de smoke de CLI para flujos de reinicio del daemon, replay de attach, kill, archive, summon y sacrifice. -- Verificación de instalación y wiring de release para rutas de paquete npm de macOS, Linux x64 y Windows x64. -- Paquetes wrapper de npm publicados: - - `@opencoven/cli` - - `@opencoven/cli-macos` - - `@opencoven/cli-linux-x64` -- Paquete puente externo de OpenClaw mantenido fuera del núcleo de OpenClaw. -- Docs de arquitectura, modelo operativo, spec de producto, marca y plan MVP. - -Now: - -- Mantener alineados el contrato versionado de la API del daemon y el trabajo de compatibilidad con clientes externos. Consulta [`docs/API-CONTRACT.md`](/API-CONTRACT). -- Mantener los docs públicos alineados con la superficie real de CLI/API. - -Next: - -- Convertir la lista de verificación del MVP en issues/milestones enlazados de GitHub. - -Later: - -- Adaptador genérico de comando tras suficiente uso real. -- Adaptadores adicionales de harness como Hermes, Aider, Gemini, OpenCode o harnesses locales definidos por el usuario. -- Hooks de política/aprobación para acciones sensibles. -- Artefactos y adjuntos de sesión más ricos. -- **Orquestación multi-harness** (Phase 1-4, TBD timeline): - - Phase 1: Protocolo de handoff y transferencia de contexto entre harnesses - - Phase 2: Descubrimiento de capabilities y enrutamiento inteligente de tareas - - Phase 3: Coordinación multi-instancia entre harnesses - - Phase 4: Dashboard de auditoría y tooling de cumplimiento -- Colaboración opcional en nube/equipo solo después de que el runtime local sea aburridamente fiable. - -### comux - -**Estado:** producto público temprano, útil como cockpit de terminal independiente y convirtiéndose en el primer cliente visual de Coven. - -Shipped: - -- Paquete público de npm `comux` y comando CLI. -- Cockpit tmux para trabajo paralelo visible. -- Aislamiento por worktree de git por carril de agente. -- Registro de launcher de agentes con múltiples CLIs de codificación. -- Lanzamientos de agente multi-selección. -- Menú de panel para flujos de inspección, merge, PR, attach y limpieza. -- Explorador de archivos, vista previa de código y affordances de revisión orientadas a diff. -- Sidebar de proyecto, controles de visibilidad de panel y flujos de reapertura. -- Rituales para configuraciones repetibles de proyecto. -- Docs de hooks de ciclo de vida y referencia de hooks generada. -- Sitio de docs y README/spec/smoke públicos. -- Visibilidad de sesiones de Coven e integración de lanzamiento mediante la ruta de puente local. -- Dirección de ritual de reparación de OpenClaw iniciada públicamente. - -Now: - -- Estabilizar la UX de sesiones de Coven en comux: list, open, launch, attach/rejoin y estados no disponibles. -- Mantener comux útil sin Coven instalado. -- Continuar el dogfooding de comux-sobre-comux para higiene de ramas/worktrees. -- Apretar los flujos de revisión/merge para que la salida del agente permanezca explícita e inspeccionable. - -Next: - -- Promover un bucle de demo crujiente `comux + Coven`: - 1. Abrir proyecto en comux. - 2. Lanzar una sesión Codex o Claude respaldada por Coven. - 3. Verla como un panel/sesión visible. - 4. Inspeccionar archivos y diffs. - 5. Hacer merge, PR, archivar o limpiar explícitamente. -- Añadir issues públicos para asperezas descubiertas durante el dogfooding. -- Mejorar el onboarding para tmux, detección de CLI de agente y disponibilidad de Coven. -- Hacer fácil generar actualizaciones de Discord desde commits entregados e issues de roadmap. - -Lab: - -- Exploración de cockpit nativo de macOS. -- Atajos de escritorio y cambio más rápido de proyecto/sesión. -- Handoff de captura del cliente de chat/captura a sesiones de comux/Coven. - -### Ruta de integración OpenClaw / captura - -**Estado:** dirección de puente opcional, no bundled en el núcleo de OpenClaw. - -Shipped: - -- Spike técnico del puente de OpenClaw completado y parqueado intencionalmente antes de fusionar al núcleo. -- Dirección del plugin externo external OpenClaw bridge plugin establecida para que el núcleo de OpenClaw permanezca limpio. -- El límite del socket/API local hace de Coven la capa de autoridad. - -Now: - -- Tratar la API de Coven como el límite de compatibilidad. -- Añadir tests de compatibilidad antes de promover el uso amplio del plugin. -- Mantener honesto el copy de captura/OpenClaw: la captura y la orquestación se sientan por encima de Coven; no reemplazan el sustrato de runtime. - -Next: - -- Documentar públicamente la ruta de plugin soportada una vez aterrice el versionado de API. -- Añadir una demo que muestre una tarea pasando de captura a runtime de Coven a revisión en comux. - -## Mapa de milestones - -```mermaid -flowchart LR - A["A. Local runtime foundation\n(mostly shipped)"] --> B["B. Visible cockpit foundation\n(shipped, stabilizing)"] - A --> C["C. Transparent community loop\n(now)"] - B --> D["D. Harness expansion\n(next/later)"] - C --> D - B --> E["E. Intake → runtime → review\n(next/lab)"] - A --> E - D --> F["F. Multi-harness orchestration\n(planned, phased)"] - E --> F - - style A fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 - style B fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 - style C fill:#C5BDED,stroke:#D4B5FF,color:#1A1825 - style D fill:#3D3547,stroke:#9A8ECD,color:#fff - style E fill:#3D3547,stroke:#9A8ECD,color:#fff - style F fill:#3D3547,stroke:#9A8ECD,color:#fff -``` - -El código de color refleja la madurez: lavanda rellena es shipped o estabilizando; pizarra contorneada es next/later. Las aristas muestran la dirección de prerrequisito, no un horario estricto. - - -## Milestones públicos - -### Milestone A — Base del runtime local - -Estado: **mostly shipped** - -- [x] Repo público y docs -- [x] CLI `coven` -- [x] Seguridad de raíz de proyecto -- [x] Adaptadores Codex y Claude -- [x] Sesiones PTY -- [x] Ledger SQLite de sesiones/eventos -- [x] Ciclo de vida del daemon -- [x] API local de sessions/events -- [x] Contrato de API versionado -- [x] Tests de compatibilidad para clientes externos - -### Milestone B — Base del cockpit visible - -Estado: **shipped, stabilizing** - -- [x] Paquete público `comux` -- [x] Paneles tmux -- [x] worktrees de git -- [x] registro de launcher de agentes -- [x] explorador de archivos / revisión por diff -- [x] rituales -- [x] menú de panel orientado a merge y PR -- [x] Visibilidad de sesiones de Coven -- [ ] Pulido de UX para attach/rejoin de Coven -- [ ] Demo documentada extremo a extremo comux + Coven - -### Milestone C — Bucle transparente de comunidad - -Estado: **now** - -- [x] Documento de roadmap público -- [ ] Etiquetas de milestone de GitHub para `roadmap`, `now`, `next`, `later`, `area:coven`, `area:comux`, `good first issue`, `help wanted` -- [ ] Primer post público de roadmap en Discord -- [ ] Cadencia semanal de actualización shipped/building/next -- [ ] Tablero público de issues enlazado desde Discord - -### Milestone D — Expansión de harness - -Estado: **next/later** - -- [x] Investigación de futuros harnesses iniciada -- [x] Contrato de adaptador documentado -- [ ] Diseño de adaptador genérico de comando a partir de uso real -- [ ] Prueba de tercer harness -- [ ] Docs de compatibilidad de harness - -### Milestone E — De captura a runtime a revisión - -Estado: **next/lab** - -- [ ] La captura del cliente de chat/captura u OpenClaw crea o solicita una tarea de Coven -- [ ] Coven posee la sesión y el log de eventos -- [ ] comux muestra la sesión para revisión -- [ ] el usuario hace merge, PR, archiva o borra trabajo explícitamente - -### Milestone F — Orquestación multi-harness (Fase 1-4) - -Estado: **planned, TBD start** - -**Fase 1: Protocolo de handoff (semanas 1-2)** -- [ ] Diseño de API de handoff e implementación TypeScript -- [ ] Formato y validación de transferencia de contexto -- [ ] Handoff explícito de harness a harness (p. ej., OpenClaw → Claude Code) -- [ ] Ledger de handoff (PostgreSQL) -- [ ] Test extremo a extremo: Cody hace handoff de un fallo de test a Claude para edición de archivo - -**Fase 2: Descubrimiento de capabilities y router (semanas 3-4)** -- [ ] Registro y declaración de capabilities de harness -- [ ] Router de tareas: auto-selección del mejor harness -- [ ] Balanceo de carga y cadenas de fallback -- [ ] Aplicación de SLA y manejo de timeouts -- [ ] Test: "Fix this bug" se enruta automáticamente al mejor harness - -**Fase 3: Coordinación multi-instancia (semanas 5-6)** -- [ ] Almacén distribuido de contexto (Redis + PostgreSQL) -- [ ] Registro de harness y heartbeat de salud -- [ ] Enrutamiento por afinidad de tarea (restricciones de recursos) -- [ ] Escalar a múltiples instancias de Coven por usuario -- [ ] Test: harnesses locales + remotos coordinan sin colisión - -**Fase 4: Auditoría y observabilidad (semanas 7-8)** -- [ ] Dashboard de auditoría: timeline de tarea y traza de handoff -- [ ] Exportación de cumplimiento (trazas redactadas) -- [ ] Métricas de Prometheus y alertas -- [ ] Visibilidad completa del trabajo orquestado -- [ ] Test: legal/cumplimiento puede consultar el historial completo - -## Modelo de transparencia en Discord - -Debemos mantener las actualizaciones de Discord ligeras y repetibles. - -### Canales sugeridos - -- `#roadmap` o un canal de tipo foro `Roadmap` para hilos de milestone. -- `#dev-updates` para resúmenes semanales. -- `#help-wanted` para issues acotadas que los miembros de la comunidad realmente puedan tomar. - -### Plantilla de actualización semanal - -```md -## OpenCoven weekly update — YYYY-MM-DD - -### Shipped -- ... - -### Building now -- ... - -### Next up -- ... - -### Help wanted -- ... - -### Links -- Roadmap: https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md -- Coven issues: https://github.com/OpenCoven/coven/issues -- comux issues: https://github.com/BunsDev/comux/issues -``` - -### Reglas para actualizaciones honestas - -- No prometas fechas a menos que ya estemos en modo release. -- Enlaza el trabajo shipped a commits, releases, issues o docs. -- Marca los experimentos como **Lab** en lugar de fingir que son elementos comprometidos del roadmap. -- Separa **runtime de Coven**, **cockpit comux** y **captura/OpenClaw** para que la gente entienda la arquitectura. -- Prefiere issues públicos pequeños sobre tareas vagas gigantes. -- Pide ayuda solo cuando la tarea tenga una condición clara de aceptación. - -## Primer post público en Discord - -```md -We opened a public roadmap for OpenCoven/Coven/comux so progress is easier to follow. - -The short version: -- Coven is the local runtime substrate: project-scoped Codex/Claude sessions, PTYs, logs, daemon API. -- comux is the visible cockpit: tmux panes, worktrees, rituals, review, merge/PR flows. -- The next serious focus is hardening the Coven API contract and polishing the comux + Coven demo loop. - -Roadmap: https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md -Coven: https://github.com/OpenCoven/coven -comux: https://github.com/BunsDev/comux - -We'll start posting lightweight shipped / building / next updates here so the work is easier to follow and easier to help with. -``` diff --git a/docs/es/SAFETY-MODEL.md b/docs/es/SAFETY-MODEL.md deleted file mode 100644 index beac6338..00000000 --- a/docs/es/SAFETY-MODEL.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "Modelo de seguridad de Coven" -description: "Límite local-first de Coven: el daemon en Rust es la autoridad, los clientes no son de confianza y las credenciales del proveedor del harness quedan fuera." ---- - -# Modelo de seguridad de Coven - -Coven es local-first, pero local no significa inofensivo. Puede lanzar harnesses de agentes en repositorios reales, reenviar input a procesos vivos y preservar logs. Este documento expone los límites de seguridad que los docs, los clientes y el código deben preservar. - -## Límite de confianza - -El daemon en Rust es el límite de autoridad. - -Cada cliente es no confiable para fines de aplicación, incluidos: - -- la CLI/TUI; -- comux; -- el plugin externo de OpenClaw; -- los scripts; y -- los futuros clientes de escritorio. - -Los clientes pueden mejorar la UX, pero no deben ser el único lugar donde se aplique una decisión sensible. - -```mermaid -flowchart TB - subgraph UntrustedZone["Untrusted for enforcement (UX layer only)"] - direction LR - CLI[coven CLI / TUI] - Comux[comux] - Plugin["OpenClaw bridge plugin"] - Scripts[Scripts / other clients] - end - - UntrustedZone -->|HTTP over Unix socket| Boundary{{Daemon authority boundary}} - - subgraph TrustedZone["Trusted for enforcement"] - direction TB - Boundary --> ValidateRoot[Canonicalize projectRoot] - ValidateRoot --> ValidateCwd[Canonicalize cwd inside root] - ValidateCwd --> AllowHarness[Allowlist harness id] - AllowHarness --> ValidateSession[Validate session id / liveness] - ValidateSession --> RouteAction[Route action id via control plane] - RouteAction --> Spawn[Spawn argv only — never sh -c] - Spawn --> Store[(SQLite store + append-only events)] - end -``` - -Cualquier cosa en **UntrustedZone** puede mentir, divergir o ser reemplazada. Cualquier cosa en **TrustedZone** es trabajo del daemon en Rust y debe fallar en cerrado ante lo desconocido. La dirección de la flecha es la única dirección en la que se permite que fluya una decisión sensible: desde lo no confiable hacia el límite, donde se revalida. - -## Autenticación y acceso local - -La solución de auth actual de Coven es un modelo de acceso local del mismo usuario, no un protocolo de autenticación de red. - -- La API del daemon corre sobre `/coven.sock`, no TCP. -- No hay OAuth, JWT, bearer token, API key, cookie de navegador, RBAC ni sesión de cuenta alojada del daemon en v0. -- Las credenciales del proveedor permanecen en el flujo local de auth del proveedor/harness, como Codex o Claude Code. -- Los clientes son no confiables para la aplicación; el daemon en Rust debe seguir revalidando cada petición sensible. -- El plugin externo de OpenClaw realiza validación del ancla de confianza del socket antes de conectarse, pero las comprobaciones de propiedad y permisos privados de `COVEN_HOME` del lado de Rust siguen siendo una prioridad de hardening. -- No expongas la API por socket cruda a través de TCP localhost, una página de navegador, un puente remoto o un flujo de emparejamiento móvil sin un diseño de auth explícito separado. - -El contrato detallado vive en [Autenticación y acceso local](/AUTH). - -## Reglas principales - -- Lanza solo con una raíz de proyecto explícita. -- Canonicaliza `projectRoot` y `cwd` antes de comparar rutas. -- Rechaza directorios de trabajo fuera de la raíz de proyecto. -- Mantén los ids de harness en allowlist hasta que exista una capa de política real. -- Construye los comandos de harness con APIs de argv. -- No ejecutes prompts mediante `sh -c`. -- Mantén las credenciales del proveedor en el flujo de autenticación del proveedor o del harness. -- Trata la API por socket como un contrato local de producto, no un detalle privado de implementación. -- Falla en cerrado ante versiones de API desconocidas, ids de acción desconocidos, harnesses no soportados e ids de sesión inválidos. - -## Datos y secretos - -Coven no debe requerir secretos almacenados en el repositorio. - -No hagas commit del estado de runtime: - -- `.coven/` -- `*.sqlite` -- `*.sqlite3` -- `*.db` -- `*.sock` -- `.env*` -- claves privadas -- certificados -- logs portadores de tokens - -Los docs y ejemplos deben usar placeholders como `/path/to/project`, `/Users/example`, `session-1` e `intent-1`. - -## Precaución con el log de eventos - -El log de eventos registra la salida del harness. Un harness puede imprimir datos sensibles si el usuario le pide inspeccionar un repositorio sensible o si la salida del comando incluye secretos. - -Guía recomendada para el usuario: - -- No ejecutes prompts no confiables en repositorios sensibles. -- No pidas a un harness que vuelque variables de entorno. -- No pegues secretos en los prompts. -- Usa proyectos descartables para demos y smoke tests. -- Ejecuta `python scripts/check-secrets.py` antes de publicar docs, fixtures o artefactos de release. - -## Postura del socket local - -La API del daemon corre sobre un socket Unix local. Está destinada a clientes locales del mismo usuario. - -Prioridades de hardening: - -- propiedad y permisos privados de `COVEN_HOME`; -- creación y limpieza seguras del socket; -- límites de tamaño de petición; -- timeouts de lectura; -- códigos de error estructurados; -- paginación de eventos; y -- tests de compatibilidad para clientes externos. - -## Control de sesión viva - -Las peticiones de input en vivo y kill requieren un id de sesión viva válido. - -Comportamiento esperado: - -- id de sesión desconocido devuelve not found; -- input/kill a sesión no viva devuelve conflicto; -- el borrado destructivo de sesión rechaza sesiones en ejecución; -- el borrado interactivo requiere confirmación explícita. - -## Automatización de escritorio y control de UI local - -Los futuros adaptadores de automatización de escritorio deben tratarse como capabilities locales privilegiadas. - -Postura requerida: - -- descubre capabilities antes de mostrar acciones; -- etiqueta claramente las acciones arriesgadas; -- requiere aprobación explícita para clics, escritura, borrado, envío, compra, publicación o modificación de estado externo; -- registra las peticiones de acción y los resultados sin registrar secretos; -- mantén los adaptadores detrás del plano de control de Coven en lugar de dejar que cada cliente se enlace directamente con APIs de automatización del SO. - -La división debe permanecer como: - -```text -client intent -> Coven policy/control plane -> adapter -> desktop/app -``` - -## Acciones externas - -Coven debe preguntar o requerir una política a nivel de host antes de las acciones que salen de la máquina o afectan servicios externos, incluidas: - -- envío de mensajes; -- envío de email; -- publicación pública; -- compra; -- borrado de datos remotos; -- push a remotos de git; y -- modificación de recursos en la nube. - -El runtime local puede hacer estas acciones visibles, pero visibilidad no es consentimiento. diff --git a/docs/es/SESSION-LIFECYCLE.md b/docs/es/SESSION-LIFECYCLE.md deleted file mode 100644 index 95f7c678..00000000 --- a/docs/es/SESSION-LIFECYCLE.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Ciclo de vida de la sesión" -description: "Cómo una sesión de Coven se mueve por los estados created, running, completed, failed, orphaned, archived y summoned desde coven run hasta la reproducción." ---- - -# Ciclo de vida de la sesión - -Este documento explica qué pasa desde `coven run` hasta la finalización, reproducción, archivado, invocación y borrado. - -## Estados del ciclo de vida - -El almacén actual registra el estado de la sesión como una cadena. Los estados comunes incluyen: - -- `created` - el registro de sesión existe antes de que comience la ejecución viva. -- `running` - el proceso de harness está activo bajo supervisión del daemon. -- `completed` - el harness salió con éxito. -- `failed` - la configuración o el lanzamiento falló antes de la finalización normal. -- `orphaned` - un daemon previo se detuvo mientras una sesión seguía marcada como en ejecución. - -El estado de archivo se almacena por separado como `archived_at`. Una sesión completada o fallida puede ocultarse de la lista activa sin cambiar su estado final. - -```mermaid -stateDiagram-v2 - [*] --> created: coven run / POST /sessions - created --> running: PTY spawn succeeds - created --> failed: validation fails / PTY spawn errors - running --> completed: harness exits 0 - running --> failed: harness exits non-zero - running --> orphaned: daemon stops while running - - completed --> archived: coven archive - failed --> archived: coven archive - orphaned --> archived: coven archive - - archived --> completed: coven summon (was completed) - archived --> failed: coven summon (was failed) - archived --> orphaned: coven summon (was orphaned) - - completed --> [*]: coven sacrifice --yes - failed --> [*]: coven sacrifice --yes - orphaned --> [*]: coven sacrifice --yes - archived --> [*]: coven sacrifice --yes -``` - -El diagrama anterior es normativo para el almacén v0. Las sesiones `running` no pueden archivarse ni sacrificarse directamente — mátalas o espera la salida primero. `created → running` es la única transición que requiere spawn de PTY; cada otra transición es un cambio de estado solo en el almacén gestionado por el daemon en Rust. - -## Ruta de lanzamiento - -El flujo normal de lanzamiento: - -1. El usuario o cliente envía una tarea a través de la CLI o la API local. -2. Coven resuelve la raíz de proyecto. -3. Coven canonicaliza la raíz de proyecto y el directorio de trabajo. -4. Coven rechaza directorios de trabajo fuera de la raíz. -5. Coven verifica que el id de harness sea compatible. -6. Coven crea un registro de sesión en SQLite. -7. El daemon hace spawn del harness en un PTY usando APIs de argv. -8. Los datos de salida y de salida del proceso se escriben como eventos. -9. El estado de la sesión y el código de salida se actualizan. - -La capa de Rust realiza las comprobaciones de autoridad incluso cuando un cliente TypeScript ya ha validado la petición para mejorar la UX. - -```mermaid -sequenceDiagram - participant Client as Client (CLI / TUI / comux / plugin) - participant Daemon as Coven daemon - participant Store as SQLite store - participant PTY as Harness PTY - - Client->>Daemon: POST /api/v1/sessions { projectRoot, cwd, harness, prompt } - Daemon->>Daemon: canonicalize projectRoot - alt projectRoot invalid - Daemon-->>Client: 400 invalid_request - end - Daemon->>Daemon: canonicalize cwd inside projectRoot - alt cwd outside root - Daemon-->>Client: 400 invalid_request (cwd fuera de la raíz del proyecto) - end - Daemon->>Daemon: lookup harness in adapter table - alt harness unknown - Daemon-->>Client: 400 invalid_request (with install hint) - end - Daemon->>Store: insert session (status=created) - Daemon->>PTY: spawn argv (prefix args + prompt) - alt spawn / initial-write fails - Daemon->>Store: update status=failed - Daemon-->>Client: 500 launch_failed (details.sessionId) - else PTY spawn ok - Daemon->>Store: update status=running - Daemon-->>Client: 200 SessionRecord - PTY-->>Store: append output / exit events - PTY->>Daemon: process exits with code - Daemon->>Store: update status=completed|failed, exit_code - end -``` - -## Registros desacoplados - -`coven run ... --detach` crea el registro de sesión sin lanzar el harness. Esto es útil para flujos de prueba y desarrollo que necesitan un registro de ledger sin iniciar un proceso externo. - -Los registros desacoplados no deben presentarse como trabajo de agente completado. - -## Attach y replay - -`coven attach ` reproduce la salida conocida del evento y sigue la salida viva cuando la sesión sigue activa. - -Para una sesión completada, attach actúa como un visor de logs. Para una sesión en ejecución, attach también reenvía input a la sesión viva del daemon. - -## Comportamiento del explorador de sesiones - -`coven sessions` elige el modo de salida según el contexto: - -- En un terminal interactivo, abre el explorador de sesiones. -- Cuando se canaliza por pipe o se ejecuta con `--plain`, imprime salida en tabla. -- `--json` imprime registros de sesión legibles por máquina para clientes locales. -- `--all` incluye sesiones archivadas. -- `--manage` fuerza el explorador. - -El explorador ofrece acciones contextuales para que los usuarios no tengan que memorizar ids de sesión. - -## Archive - -Archive oculta una sesión no en ejecución de la lista activa por defecto preservando el registro de sesión y el log de eventos. - -```sh -coven archive -``` - -Usa archive para trabajo antiguo que debe permanecer inspeccionable. - -## Summon - -Summon restaura una sesión archivada a la lista activa y luego la reproduce/sigue: - -```sh -coven summon -``` - -Summon no re-ejecuta el prompt original del harness. Cambia el estado de archivo y abre el registro existente. - -## Sacrifice - -Sacrifice borra permanentemente una sesión no en ejecución y propaga el borrado a sus eventos: - -```sh -coven sacrifice --yes -``` - -El comando rechaza sesiones vivas. El explorador interactivo pide al usuario que escriba `sacrifice` antes de borrar. - -Usa sacrifice solo cuando la sesión y sus logs deban eliminarse del ledger local. - -## Recuperación de huérfanos - -Si el daemon arranca y encuentra sesiones marcadas como `running` de una vida anterior del daemon, esas sesiones se marcan `orphaned`. - -Una sesión huérfana significa que Coven ya no posee un proceso vivo para ese registro. El log de eventos puede seguir siendo útil, pero las operaciones de input en vivo y kill deben fallar. - -## Durabilidad de eventos - -Los eventos son registros append-only en SQLite. Esto da a los clientes una fuente estable de reproducción incluso cuando el proceso PTY original ha salido. - -No escribas intencionalmente secretos, volcados de entorno, URLs privadas o salida de comando portadora de tokens en los eventos. Coven no puede garantizar que la salida del harness esté libre de secretos, así que los usuarios deben evitar ejecutar prompts no confiables en repositorios sensibles. diff --git a/docs/es/TROUBLESHOOTING.md b/docs/es/TROUBLESHOOTING.md deleted file mode 100644 index 8d04902e..00000000 --- a/docs/es/TROUBLESHOOTING.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: "Solución de problemas de Coven" -description: "Soluciona problemas de Coven: comandos coven faltantes, errores de socket del daemon, harness no encontrado, sesiones huérfanas y raíces de proyecto rechazadas." ---- - -# Solución de problemas de Coven - -Empieza con: - -```sh -coven doctor -``` - -`doctor` es la forma más rápida de comprobar la preparación del almacén, el proyecto, el daemon y los harnesses. - -```mermaid -flowchart TD - Start([Something broken?]) --> Doctor["coven doctor"] - Doctor --> Store{store ok?} - Store -- no --> CovenHome["Check $COVEN_HOME ownership + perms"] - Store -- yes --> Project{project ok?} - Project -- no --> ProjectFix["Run from inside a project tree"] - Project -- yes --> DaemonChk{daemon running?} - DaemonChk -- no --> StartDaemon["coven daemon start / restart"] - DaemonChk -- yes --> Harness{harness detected?} - Harness -- no --> InstallHarness["Install harness CLI\n(see install hint)"] - Harness -- yes --> RunChk{coven run works?} - RunChk -- no --> RunFix["Check provider auth\n(codex login / claude doctor)"] - RunChk -- yes --> AttachChk{attach behavior expected?} - AttachChk -- no --> AttachFix["Session may be archived/orphaned\nUse coven sessions --all"] - AttachChk -- yes --> Done([Working]) - - CovenHome --> Doctor - ProjectFix --> Doctor - StartDaemon --> Doctor - InstallHarness --> Doctor - RunFix --> Doctor - AttachFix --> Doctor -``` - -Sigue la rama que falle. Casi cualquier problema en el resto de esta página es una de estas ramas en detalle. - -## Comando `coven` no encontrado - -Si usas npm: - -```sh -npx @opencoven/cli doctor -pnpm dlx @opencoven/cli doctor -``` - -Si compilas desde fuente: - -```sh -cargo run -p coven-cli -- doctor -``` - -Si instalaste un binario nativo, asegúrate de que su directorio esté en `PATH`. - -## Harness faltante - -`coven doctor` imprime pistas de instalación para cada harness incorporado. - -Codex: - -```sh -npm install -g @openai/codex -codex login -``` - -Claude Code: - -```sh -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -Luego reintenta: - -```sh -coven doctor -``` - -## Daemon no disponible - -Arráncalo o reinícialo: - -```sh -coven daemon start -coven daemon status -coven daemon restart -``` - -Si un cliente no puede conectarse, verifica que esté usando el mismo `COVEN_HOME` que la CLI. - -## Salud y presión del sistema - -Si las sesiones se sienten lentas, el daemon es lento al iniciar o `coven doctor` tiene éxito pero el trabajo del harness se atasca, la máquina subyacente puede estar bajo presión de CPU, memoria o disco. - -`coven pc` muestra un informe local del sistema sin lanzar un harness. Todas las operaciones de lectura son libres de efectos secundarios: - -```sh -coven pc # full report: CPU, memory, disk, top processes -coven pc status # one-line health summary -coven pc top --n 10 # top-N processes by CPU usage -coven pc disk # disk usage breakdown -``` - -Las operaciones de relief mutan el estado del sistema y requieren una puerta explícita `--confirm`: - -```sh -coven pc kill --confirm # SIGTERM with PID identity re-check -coven pc cache clear --confirm # clear ~/Library/Caches + /Library/Caches -``` - -`coven pc` es actualmente primero para macOS. Consulta [Diagnósticos y relief](GETTING-STARTED.md#diagnostics-and-relief) en Empezar para la referencia completa del comando. - -## Sesiones en ejecución obsoletas - -Si un daemon se detuvo mientras había sesiones en ejecución, esos registros pueden convertirse en `orphaned` en el siguiente arranque del daemon. - -Usa: - -```sh -coven sessions --all -``` - -Luego ve los logs, archiva el registro o sacrifícalo si ya no es útil. - -## La sesión no acepta input - -El input solo funciona para sesiones vivas propiedad del daemon. - -Si la sesión está completada, fallida, archivada u huérfana, attach funciona como replay/visualización de logs en lugar de input en vivo. - -## `cwd` rechazado - -Coven rechaza directorios de trabajo que se resuelvan fuera de la raíz de proyecto. - -Usa una ruta dentro del proyecto: - -```sh -coven run codex "inspect package" --cwd packages/cli -``` - -No uses trucos de symlink ni rutas padre para escapar del límite del proyecto. - -## Versión de API rechazada - -Los nuevos clientes deben usar `/api/v1`. - -Comprueba la compatibilidad del daemon: - -```text -GET /api/v1/health -``` - -Si el cliente espera una API más nueva que la que expone el daemon, actualiza Coven o el cliente para que sus versiones soportadas se solapen. - -## `coven sessions` imprimió una tabla en lugar de abrir el explorador - -Coven abre el explorador solo en un terminal interactivo. - -Forzar el modo explorador: - -```sh -coven sessions --manage -``` - -Forzar el modo tabla: - -```sh -coven sessions --plain -``` - -## Confusión con archive, summon y sacrifice - -- Archive oculta una sesión no en ejecución pero conserva los eventos. -- Summon restaura una sesión archivada a la lista activa. -- Sacrifice borra permanentemente una sesión no en ejecución y sus eventos. - -Usa el explorador interactivo cuando sea posible: - -```sh -coven sessions --all --manage -``` - -## Fallo del escaneo de secretos - -Ejecuta: - -```sh -python scripts/check-secrets.py -``` - -Si falla, elimina el secreto del árbol de trabajo. Si un secreto entró en el historial de git, rota la credencial antes de reescribir el historial o publicar. - -No pegues valores de secretos detectados en issues, logs, docs o chat. - -## Las comprobaciones del contribuidor fallan tras ediciones solo de docs - -Como mínimo, ejecuta: - -```sh -python scripts/check-secrets.py -git diff --check -``` - -Para cambios de código, ejecuta la puerta completa: - -```sh -cargo fmt --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace --locked -python scripts/check-secrets.py -``` diff --git a/docs/es/harnesses/claude-code.md b/docs/es/harnesses/claude-code.md deleted file mode 100644 index 895939ae..00000000 --- a/docs/es/harnesses/claude-code.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -summary: "Ejecuta Anthropic Claude Code bajo supervisión de Coven. Id de harness `claude`." -read_when: - - Configurar Claude Code para Coven - - Diagnosticar fallos específicos de Claude -title: "Harness de Claude Code" -description: "Ejecuta la CLI de Anthropic Claude Code bajo Coven con harness id claude, un PTY limitado al proyecto y los flujos estándar de attach y ritual." ---- - - -Claude Code es la CLI de agente de codificación de Anthropic. Coven la envuelve en un PTY limitado al proyecto para que los lanzamientos, attaches y rituales funcionen igual que para cualquier otro harness. - -| Campo | Valor | -|---|---| -| Id de harness | `claude` | -| Instalación | `npm install -g @anthropic-ai/claude-code` | -| Auth | `claude doctor` (una sola vez, lado de Anthropic) | -| Comprobación de doctor | `coven doctor` informa la ruta y versión de Claude resueltas. | - -## Configuración - - - - ```bash - npm install -g @anthropic-ai/claude-code - ``` - - - ```bash - claude doctor - ``` - Las credenciales del proveedor se quedan con Claude Code. Coven nunca las lee. - - - ```bash - coven doctor - ``` - La salida debe incluir `claude: ok (/usr/local/bin/claude)`. - - - ```bash - coven run claude "polish this UI" - ``` - - - -## Flags por sesión - -```bash -coven run claude "refactor for clarity" --cwd packages/web --title "Web refactor" -``` - -- `--cwd` — canonicalizado dentro de la raíz de proyecto. -- `--title` — establece un título legible en el explorador de sesiones. -- `--json` — imprime metadatos estructurados de lanzamiento para clientes. - -## Límite de auth del proveedor - -Claude Code posee su propio flujo OAuth y caché de tokens. Coven nunca lee claves de Anthropic ni cookies de sesión. - -## Solución de problemas - -| Síntoma | Causa probable | Solución | -|---|---|---| -| `coven doctor` informa `claude` faltante | Claude Code no está en `PATH` | `npm install -g @anthropic-ai/claude-code`, luego vuelve a ejecutar doctor. | -| Claude pide login | Auth sin completar | `claude doctor`. | -| La sesión muestra una pausa larga de pre-flight | Claude resolviendo configuración | Solo la primera ejecución; los lanzamientos posteriores son rápidos. | - -## Cómo supervisa Coven a Claude Code - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI - participant D as Coven daemon - participant Cl as Claude PTY - participant An as Anthropic API - - U->>C: coven run claude "refactor for clarity" - C->>D: POST /api/v1/sessions - D->>D: canonicalize root + cwd - D->>D: lookup adapter for "claude" - D->>Cl: spawn claude (prefix: --print for non-interactive, none for interactive) - Cl->>An: provider auth (uses Anthropic local credentials — Coven does not see) - An-->>Cl: model response stream + tool calls - Cl-->>D: stdout / exit events - D-->>C: SessionRecord (id, status=running) - C-->>U: print session id, switch to attach view -``` - -Las llamadas a herramientas de Claude Code se ejecutan dentro del proceso de Claude — Coven no las arbitra. El PTY captura su salida como stdout/stderr ordinario. - - -## Relacionado - -- [Instalación de CLIs de harness](/harnesses/installing) -- [Límite de auth del proveedor](/harnesses/provider-auth) -- [Solución de problemas de harness](/harnesses/troubleshooting) diff --git a/docs/es/harnesses/codex.md b/docs/es/harnesses/codex.md deleted file mode 100644 index aead5856..00000000 --- a/docs/es/harnesses/codex.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -summary: "Ejecuta la CLI de OpenAI Codex bajo supervisión de Coven. Id de harness `codex`." -read_when: - - Configurar Codex para Coven - - Diagnosticar fallos específicos de Codex -title: "Harness de Codex" -description: "Ejecuta la CLI de OpenAI Codex bajo Coven con harness id codex, un PTY limitado al proyecto y los flujos habituales de sesión, attach y ritual." ---- - - -Codex es la CLI de agente de codificación de OpenAI. Coven la envuelve en un PTY limitado al proyecto para que los lanzamientos, attaches y rituales funcionen igual que para cualquier otro harness. - -| Campo | Valor | -|---|---| -| Id de harness | `codex` | -| Instalación | `npm install -g @openai/codex` | -| Auth | `codex login` (una sola vez, lado de OpenAI) | -| Comprobación de doctor | `coven doctor` informa la ruta y versión de Codex resueltas. | - -## Configuración - - - - ```bash - npm install -g @openai/codex - ``` - Otros métodos de instalación (Homebrew cask, gestores de paquetes) están listados en el [repo de Codex](https://github.com/openai/codex). - - - ```bash - codex login - ``` - Las credenciales del proveedor se quedan con Codex. Coven nunca las lee. - - - ```bash - coven doctor - ``` - La salida debe incluir una línea como `codex: ok (/usr/local/bin/codex)`. - - - ```bash - coven run codex "fix the failing tests" - ``` - - - -## Flags por sesión - -```bash -coven run codex "audit this repo" --cwd packages/cli --title "CLI audit" -``` - -- `--cwd` — canonicalizado dentro de la raíz de proyecto. -- `--title` — establece un título legible en el explorador de sesiones. -- `--json` — imprime metadatos estructurados de lanzamiento para clientes. - -## Límite de auth del proveedor - -Codex posee su propio flujo OAuth y caché de tokens. Si ves `Invalidated OAuth token`, ejecuta `codex login` de nuevo. Coven mantendrá el registro de sesión existente para que puedas relanzar con el mismo título. - -Para la ruta de rescate local: - -```bash -coven patch openclaw "fix Codex auth profile order after invalidated OAuth token" -``` - -## Solución de problemas - -| Síntoma | Causa probable | Solución | -|---|---|---| -| `coven doctor` informa `codex` faltante | Codex no está en `PATH` | `npm install -g @openai/codex`, luego vuelve a ejecutar doctor. | -| Codex pide login en cada ejecución | Token obsoleto | `codex login`. | -| La sesión se cuelga al iniciar | Codex esperando un prompt de TTY | Desadjunta con `Ctrl-]`, relanza con `coven run` directamente. | - -## Cómo supervisa Coven a Codex - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI - participant D as Coven daemon - participant Cx as Codex PTY - participant Op as OpenAI API - - U->>C: coven run codex "audit this repo" - C->>D: POST /api/v1/sessions - D->>D: canonicalize root + cwd - D->>D: lookup adapter for "codex" - D->>Cx: spawn codex (prefix: exec --skip-git-repo-check --color never) - Cx->>Op: provider auth (uses ~/.codex credentials — Coven does not see) - Op-->>Cx: model response stream - Cx-->>D: stdout / exit events - D-->>C: SessionRecord (id, status=running) - C-->>U: print session id, switch to attach view -``` - -La línea punteada digna de notar: Coven nunca se conecta a la API de OpenAI por sí mismo. La ruta de credenciales es **CLI de Codex ↔ OpenAI**, con Coven solo observando la salida del PTY. - - -## Relacionado - -- [Instalación de CLIs de harness](/harnesses/installing) -- [Límite de auth del proveedor](/harnesses/provider-auth) -- [Solución de problemas de harness](/harnesses/troubleshooting) diff --git a/docs/es/harnesses/copilot-cli.md b/docs/es/harnesses/copilot-cli.md deleted file mode 100644 index 984eb331..00000000 --- a/docs/es/harnesses/copilot-cli.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -summary: "Ejecuta GitHub Copilot CLI bajo la supervisión de Coven. Id de harness `copilot`." -read_when: - - Configurando GitHub Copilot CLI para Coven - - Diagnosticando fallos de harness específicos de Copilot -title: "Harness de Copilot CLI" -description: "Ejecuta la GitHub Copilot CLI bajo la supervisión de Coven con el id de harness copilot, sesiones ancladas al proyecto y los flujos habituales de attach y rituales." ---- - - -GitHub Copilot CLI es la CLI de agente de código de GitHub. Coven usa un PTY -anclado al proyecto tanto para lanzamientos interactivos como one-shot, así -que las sesiones, attaches y rituales funcionan igual que con cualquier otro -harness. - -| Campo | Valor | -|---|---| -| Id de harness | `copilot` | -| Instalación | `npm install -g @github/copilot` o `brew install --cask copilot-cli` | -| Auth | `copilot login` (una vez, del lado de GitHub) | -| Chequeo de doctor | `coven doctor` informa la disponibilidad de Copilot CLI y la pista de instalación cuando falta. | - -## Configuración - - - - ```bash - npm install -g @github/copilot - # o - brew install --cask copilot-cli - ``` - - - ```bash - copilot login - ``` - Las credenciales de GitHub se quedan con Copilot. Coven nunca las lee. - - - ```bash - coven doctor - ``` - La sección Harnesses debe incluir `[OK] Copilot CLI` con el ejecutable `copilot` resuelto. - - - ```bash - coven run copilot "arregla los tests que fallan" - ``` - - - -## Mapeo de permisos - -La superficie de permisos de Copilot son flags booleanos/multi-token en lugar -de un único flag de modo, así que `--permission` de Coven se mapea a listas -de argv: - -| Política de Coven | Argv de Copilot | Efecto | -|---|---|---| -| `full` | `--allow-all` | Todas las herramientas, rutas y URLs se ejecutan sin confirmación. | -| `read-only` | `--deny-tool write --deny-tool shell` | Las escrituras de archivos y los comandos de shell se deniegan directamente (las reglas de denegación ganan a cualquier regla de permiso). Las lecturas dentro del directorio de trabajo siguen permitidas. | -| *(ninguna)* | *(sin flags)* | Aplican los valores por defecto de Copilot. En modo no interactivo, Copilot auto-deniega cualquier herramienta que habría pedido confirmación. | - -## Continuidad de sesión - -Copilot soporta ids de sesión preasignados: `coven chat` envía -`--session-id ` en el primer turno y el mismo flag en los turnos -siguientes. `--session-id` crea una sesión nueva bajo un UUID elegido y -también reanuda una existente, así que los ids obsoletos se auto-reparan en -una conversación nueva en lugar de fallar. - -## Solución de problemas - -| Síntoma | Causa probable | Arreglo | -|---|---|---| -| `coven doctor` reporta `copilot` como faltante | Copilot CLI no está en `PATH` | `npm install -g @github/copilot` (o `brew install --cask copilot-cli`) y re-ejecuta doctor. | -| Las ejecuciones fallan de inmediato con un error de auth | Sin sesión iniciada | `copilot login`. | -| `Error: Model "auto" does not support reasoning effort configuration` | `--model auto` combinado con `--think`/`--speed` | Quita el flag de esfuerzo o elige un modelo concreto. | -| La sesión no puede leer un archivo fuera del repo | Verificación de rutas de Copilot | Re-lanza con `--add-dir `. | - -## Relacionado - -- [Instalar las CLIs de harness](/harnesses/installing) -- [Frontera de auth del proveedor](/harnesses/provider-auth) -- [Guía de adaptadores de harness](/HARNESS-ADAPTERS) diff --git a/docs/es/harnesses/installing.md b/docs/es/harnesses/installing.md deleted file mode 100644 index 0e3bf353..00000000 --- a/docs/es/harnesses/installing.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -summary: "Cómo Coven detecta las CLIs de harness y qué instalar para cada una." -read_when: - - Resolver errores de harness faltante - - Configurar una nueva máquina para Coven -title: "Instalar CLIs de harness para Coven" -description: "Cómo Coven detecta las CLIs de harness en PATH y qué paquetes instalar para Codex, Claude Code y otros harnesses de agente de codificación soportados." ---- - -Coven **no** incluye las CLIs de harness. Cada harness compatible es una CLI independiente que Coven detecta en `PATH` en el momento del lanzamiento y supervisa a través de un adaptador PTY. Esta página muestra los comandos de instalación para cada harness v0 y explica cómo `coven doctor` informa los resultados de detección. - -## Cómo funciona la detección - -Tanto `coven doctor` como `POST /api/v1/sessions` resuelven un id de harness (`codex`, `claude`, …) a un nombre de ejecutable en `PATH` usando la tabla de adaptadores en [Adaptadores de harness](/HARNESS-ADAPTERS). Si el binario falta, Coven falla en cerrado con una pista de instalación en lugar de intentar lanzar. - -```mermaid -flowchart LR - Run["coven run codex prompt"] --> Daemon[Coven daemon] - Daemon --> Lookup{harness id known?} - Lookup -- no --> Reject1[Reject: unsupported harness] - Lookup -- yes --> Resolve{executable on PATH?} - Resolve -- no --> Hint["Reject: install hint via coven doctor"] - Resolve -- yes --> Spawn[Spawn validated argv in PTY] -``` - -El daemon revalida el id de harness en cada petición de lanzamiento. Los clientes no pueden ampliar la allowlist enviando un argv o ruta diferente; solo se aceptan los ids de adaptador incorporados. - -## Harnesses v0 compatibles - -| Id de harness | Ejecutable | Comando de instalación | Login del proveedor | Página de detalle | -|---|---|---|---|---| -| `codex` | `codex` | `npm install -g @openai/codex` | `codex login` | [Harness de Codex](/harnesses/codex) | -| `claude` | `claude` | `npm install -g @anthropic-ai/claude-code` | `claude doctor` | [Harness de Claude Code](/harnesses/claude-code) | -| `copilot` | `copilot` | `npm install -g @github/copilot` | `copilot login` | [Harness de Copilot CLI](/harnesses/copilot-cli) | - -Otras CLIs (Hermes, Aider, Gemini CLI, Cline, comandos personalizados) **no** forman parte de v0. Consulta [Notas sobre futuros harnesses](/FUTURE-HARNESSES) para conocer la dirección del adaptador. - -## Instalación paso a paso - - - - Elige el harness que quieras manejar primero. Puedes instalar más después. - - ```bash - # OpenAI Codex - npm install -g @openai/codex - - # Anthropic Claude Code - npm install -g @anthropic-ai/claude-code - - # GitHub Copilot CLI - npm install -g @github/copilot - ``` - - Otras rutas de instalación (Homebrew, gestores de paquetes, compilar desde fuente) están documentadas en el README propio de cada proyecto. Coven solo requiere que el binario esté en `PATH` bajo el nombre de ejecutable esperado. - - - - Coven nunca toca las credenciales del proveedor. Ejecuta el flujo de login propio de cada CLI una vez. - - ```bash - codex login - claude doctor - copilot login - ``` - - Consulta [Límite de auth del proveedor](/harnesses/provider-auth) para conocer la justificación. - - - - ```bash - coven doctor - ``` - - Salida esperada (abreviada): - - ```text - store: ok - project: ok (/path/to/project) - daemon: running (pid 12345) - codex: ok (/usr/local/bin/codex 0.x.y) - claude: ok (/usr/local/bin/claude 0.x.y) - ``` - - Si una fila muestra `missing`, doctor también imprime el comando exacto de instalación mostrado en la tabla anterior. - - - - ```bash - coven run codex "describe this repo" - coven run claude "polish the CLI help text" - ``` - - - -## Actualizar un harness - -Coven no auto-actualiza las CLIs de harness. Trátalas como instalaciones globales ordinarias de npm (u otro gestor de paquetes): - -```bash -npm install -g @openai/codex@latest -npm install -g @anthropic-ai/claude-code@latest -npm install -g @github/copilot@latest -``` - -Después de actualizar, vuelve a ejecutar `coven doctor` para confirmar que la ruta/versión resuelta aún coincide con lo que esperas. - -## Ubicaciones personalizadas de ejecutable - -Si un harness está instalado bajo un directorio fuera de `PATH` (por ejemplo, un `node_modules/.bin` local del proyecto), asegúrate de que ese directorio esté en `PATH` **antes** de que arranque el daemon. Coven respeta el entorno del proceso del daemon, no el entorno del shell que lo invoca, al lanzar PTYs. - -Si cambias `PATH` a nivel de sistema, reinicia el daemon: - -```bash -coven daemon restart -coven doctor -``` - -## Solución de problemas - -| Síntoma | Causa probable | Solución | -|---|---|---| -| `coven doctor` informa un harness como `missing` incluso tras instalar | El daemon no recogió el nuevo `PATH` del shell | `coven daemon restart`, luego `coven doctor`. | -| Doctor encuentra el binario pero `coven run` falla inmediatamente | Auth del proveedor incompleta | Re-ejecuta `codex login` / `claude doctor` / `copilot login`. Consulta [auth del proveedor](/harnesses/provider-auth). | -| Doctor muestra una versión obsoleta | Binario más antiguo más temprano en `PATH` | `which -a codex` (o `claude`) y elimina el duplicado. | -| Doctor informa `unsupported harness` | Error tipográfico en el id de harness | Usa uno de los ids de la tabla anterior. | - - -## Relacionado - -- [Harnesses](/harnesses/index) -- [Harness de Codex](/harnesses/codex) -- [Harness de Claude Code](/harnesses/claude-code) -- [Adaptadores de harness](/HARNESS-ADAPTERS) -- [Notas sobre futuros harnesses](/FUTURE-HARNESSES) diff --git a/docs/es/harnesses/provider-auth.md b/docs/es/harnesses/provider-auth.md deleted file mode 100644 index 5b18f6ee..00000000 --- a/docs/es/harnesses/provider-auth.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -summary: "Coven no almacena credenciales del proveedor. Cada harness sigue usando su propio login." -read_when: - - Auditar dónde viven las credenciales - - Decidir qué se le permite leer o proxificar a Coven - - Revisar el límite de seguridad antes de desplegar Coven en una máquina compartida -title: "Límite de auth del proveedor del harness" -description: "Coven nunca almacena ni proxifica credenciales del proveedor. Cada harness sigue usando su propio flujo de login para OpenAI, Anthropic u otros proveedores." ---- - -Coven supervisa PTYs de harness. Nunca lee, proxifica, persiste ni emite credenciales del proveedor. Cada harness compatible sigue usando **su propio** flujo de login para OpenAI, Anthropic o cualquier futuro proveedor con el que hable. Esta página registra por qué, qué significa eso en la práctica y el límite exacto que el daemon en Rust aplica. - -## TL;DR - -- Los tokens del proveedor viven donde sea que el harness ya los ponga — típicamente `~/.codex/`, `~/.config/anthropic/` o un keychain del sistema gestionado por esa CLI. -- El daemon de Coven nunca los lee, nunca los almacena en SQLite, nunca los reenvía por la API por socket y nunca los registra en el ledger de eventos. -- `coven doctor` solo comprueba si el binario del harness existe; **no** prueba credenciales del proveedor. Cada harness ya entrega su propio `login` / `doctor` para eso. -- Trata a Coven como si tuviera conocimiento **cero** del estado de auth del proveedor. El límite es intencional. - -## Por qué Coven se niega a poseer credenciales - -```mermaid -flowchart LR - User[Developer] -->|once| HarnessLogin["harness login (codex login / claude doctor)"] - HarnessLogin --> HarnessStore[("Provider credential store\n~/.codex, keychain, etc.")] - - User -->|every run| CovenRun["coven run codex prompt"] - CovenRun --> Daemon[Coven daemon] - Daemon -.->|never reads| HarnessStore - Daemon --> PTY[Harness PTY] - PTY --> HarnessStore - PTY --> Provider[Provider API] -``` - -La flecha que importa es la que falta: el daemon no tiene línea punteada hacia el almacén de credenciales del proveedor. Tres razones: - -1. **Menor radio de impacto.** Un daemon, socket o cliente comprometido de Coven no puede filtrar tokens del proveedor que nunca tuvo. Un bug en el log de eventos no puede registrar accidentalmente un token que Coven nunca poseyó. -2. **Sin drift de credenciales.** Codex, Claude Code y los futuros harnesses iteran sobre sus propios flujos de auth (refresh OAuth, códigos de dispositivo, claves en el dispositivo). Coven tendría que perseguir cada cambio. Al quedarse fuera, nunca nos desincronizamos. -3. **Claridad de auditoría.** Cuando algo va mal con facturación, límites de tasa o tokens revocados, el usuario sabe que la respuesta vive en **un** lugar — la CLI propia del harness. Coven no es una capa de credenciales que debugear. - -## Qué significa esto en cada superficie - -### CLI - -`coven run codex|claude ` lanza el harness con un vector de argumentos vacío aparte del prompt validado y los args de prefijo del adaptador. No inyecta `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` ni ninguna env var portadora de tokens. Si el harness necesita una credencial, la lee de la misma manera que si se lanzara directamente desde tu shell. - -### API del daemon - -`POST /api/v1/sessions` acepta una raíz de proyecto, cwd, id de harness, prompt y título opcional. No hay campo para una API key, token OAuth, refresh token, id de cuenta o id de organización. El esquema está documentado en [Contrato de la API](/API-CONTRACT) — ninguno de esos campos existe. - -### Log de eventos - -El log de eventos append-only registra el stdout/stderr del harness tal como se emite. El daemon no introspecciona ni redacta; eso significa que si **tú** pides al harness que imprima `cat ~/.codex/auth.json`, la salida **sí** aterrizará en el ledger. Consulta el [Modelo de seguridad](/SAFETY-MODEL#event-log-caution) para la guía del lado del usuario. - -### Integraciones de cliente - -Los clientes (comux, el cliente de chat/captura, el plugin de OpenClaw) se conectan al socket local. No pueden obtener tokens del proveedor desde el daemon porque el daemon no los tiene. Cualquier cliente que quiera mostrar "logged in as ..." debe llamar directamente al comando de estado propio del harness. - -## Login del proveedor por harness - -| Harness | Comando de login | Dónde viven las credenciales | Notas | -|---|---|---|---| -| `codex` | `codex login` | `~/.codex/auth.json` (o keychain de plataforma, según la versión de Codex) | Usa `codex logout` para revocar. Coven no necesita reiniciarse. | -| `claude` | `claude doctor` y luego sigue las indicaciones | `~/.config/anthropic/` y/o keychain del sistema | `claude doctor` también es una comprobación general de salud; Coven solo depende de que el binario esté presente. | -| `copilot` | `copilot login` | `~/.copilot/` (token del device-flow de GitHub gestionado por la CLI) | Usa `copilot logout` para revocar. El acceso a Copilot del lado de GitHub lo gobierna tu plan de GitHub. | - -Si el flujo `login` del harness en sí tiene un problema (refresh token expirado, org revocada, fallo de red), Coven lo presenta como una salida normal del harness — la sesión termina con cualquier código de salida que devuelva la CLI, y el log de eventos contiene el mensaje de error impreso por la CLI. - -## Qué aplica Coven - -La responsabilidad del daemon es **quedarse fuera de la ruta de credenciales**. Concretamente: - -- El daemon no lee variables de entorno que parezcan credenciales del proveedor antes de lanzar un harness. -- El daemon no inyecta env vars del proveedor en el hijo PTY más allá de heredar lo que el propio proceso del daemon recibió al arrancar. -- La CLI no acepta una flag `--token`, `--api-key`, `--openai-key` o similar en `coven run`. Si ves una en un fork o PR, eso es una regresión — por favor, abre una issue. -- La API por socket no acepta campos de credenciales. Los campos desconocidos se ignoran; los campos explícitos de credencial serían rechazados y tratados como una violación del contrato. - -## Qué debe hacer el usuario - -Como Coven se niega a poseer credenciales, **el usuario** es responsable de: - -- Ejecutar el flujo de `login` / `doctor` propio de cada harness al menos una vez antes de esperar que `coven run` tenga éxito. -- Rotar tokens del proveedor a través de la CLI del harness cuando sea necesario. -- Tratar cualquier salida del harness que imprima una credencial (porque tú lo pediste) como registrada en el ledger — límpiala con [`coven sacrifice`](/SESSION-LIFECYCLE#sacrifice) si es necesario. - - -## Relacionado - -- [Autenticación y acceso local](/AUTH) -- [Modelo de seguridad](/SAFETY-MODEL) -- [Instalar CLIs de harness](/harnesses/installing) -- [Adaptadores de harness](/HARNESS-ADAPTERS) -- [Harness de Codex](/harnesses/codex) -- [Harness de Claude Code](/harnesses/claude-code) diff --git a/docs/es/index.md b/docs/es/index.md deleted file mode 100644 index ecc9e38e..00000000 --- a/docs/es/index.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -summary: "Coven es un sustrato de runtime local-first para familiares de IA persistentes. Un daemon supervisa cada harness de agente de codificación con sesiones limitadas al proyecto, eventos append-only y una API tipada por socket local." -read_when: - - Presentar OpenCoven y Coven a personas recién llegadas - - Decidir si instalar Coven para trabajo local con agentes -title: "Coven" -description: "Coven es un runtime local-first que supervisa CLIs de agentes de codificación en sesiones por proyecto con eventos append-only y API por socket local tipada." ---- - - -
- OpenCoven -
-

Trae cualquier familiar al círculo.

-

OpenCoven es un ecosistema abierto para familiares de IA persistentes. Coven es el sustrato de runtime local que supervisa cada harness — Codex, Claude Code y los futuros Hermes, Aider y Gemini CLIs — dentro de límites explícitos del proyecto.

-

Lanza una sesión, observa el PTY, adjúntate más tarde, archiva cuando termines. Un daemon, un socket, todos los familiares en igualdad de condiciones.

-
-
- - - - Instala Coven, ejecuta `coven doctor` y lanza una sesión de harness limitada al proyecto. - - - Daemon, supervisión de PTY, validación de la raíz del proyecto, sesiones, eventos y autoridad del socket local. - - - Comandos `coven` actuales: run, sessions, attach, daemon, doctor, archive, summon y sacrifice. - - - -## ¿Qué es Coven? - -Coven es un **sustrato de runtime local-first**: un único daemon en Rust que posee los PTYs de los harnesses, el estado de las sesiones y un registro append-only de eventos en tu propia máquina. Clientes como la CLI/TUI `coven`, el cockpit comux y el plugin externo OpenClaw coordinan a través de un único contrato versionado HTTP-sobre-socket-Unix. - -**¿Para quién es?** Desarrolladores y operadores que quieren que sus familiares de IA sigan ejecutándose localmente, recuerden lo que hicieron y permanezcan dentro de límites del proyecto que puedas auditar. - -**¿Qué lo hace diferente hoy?** - -- **Local-first** — el daemon, el almacén y el socket viven bajo `$COVEN_HOME`. Sin relay en la nube, sin OAuth del daemon. -- **Neutral respecto al harness** — Codex y Claude Code hoy, con una barra de adaptador documentada para futuros harnesses. Mismo ciclo de vida, mismos rituales. -- **Limitado al proyecto** — cada lanzamiento lleva una raíz de proyecto explícita y un directorio de trabajo canonicalizado. El daemon en Rust revalida cada petición. -- **Inspeccionable** — las sesiones y los eventos son filas de SQLite que puedes explorar con `coven sessions`, reproducir con `coven attach` o sacrificar cuando ya no las necesites. -- **Con licencia MIT** — empaquetado para early adopters bajo `@opencoven/*`, comando siempre `coven`. - -**¿Qué necesitas?** Una toolchain estable de Rust (o el wrapper publicado `@opencoven/cli`), al menos una CLI de harness compatible en `PATH` y un proyecto donde ejecutarlo. - -## Cómo funciona - -```mermaid -flowchart LR - A["coven CLI / TUI"] --> B["Coven daemon"] - C["comux cockpit"] --> B - E["OpenClaw bridge plugin"] --> B - B --> F["Codex PTY"] - B --> G["Claude Code PTY"] - B --> H["Future harness PTYs"] - B --> I[("SQLite session ledger")] - B --> J[("Append-only event log")] -``` - -El daemon es la única fuente de verdad para las sesiones, el ciclo de vida del PTY y el enrutamiento de capabilities. - -## Capacidades clave - - - - Codex y Claude Code lanzados a través de una única capa de PTY supervisada. - - - Cada sesión fija una raíz de proyecto canónica y se niega a moverse. - - - Reproduce la salida, recupérate de reinicios del daemon y audita lo que un harness hizo realmente. - - - Archive, summon y sacrifice — verbos explícitos y seguros para principiantes alrededor de operaciones destructivas. - - - `GET /api/v1/health` primero; luego sesiones, eventos, capabilities y acciones por socket Unix. - - - comux y el puente OpenClaw se integran como clientes del socket, no como autoridades de lanzamiento. - - - -## Inicio rápido - - - - ```bash - npm install -g @opencoven/cli - ``` - ¿Compilando desde fuente? Consulta [Empezar](/GETTING-STARTED). - - - ```bash - coven doctor - ``` - `doctor` informa si `codex` y `claude` están en `PATH`, si el socket del daemon puede enlazarse y qué instalar a continuación. - - - ```bash - coven daemon start - coven daemon status - ``` - - - ```bash - cd /path/to/your/project - coven run codex "describe this repo" - ``` - O abre el explorador humano de sesiones: - - ```bash - coven sessions - ``` - - - -¿Necesitas la guía completa de instalación y configuración para desarrolladores? Consulta [Empezar](/GETTING-STARTED). - -## Explorador de sesiones - -`coven sessions` abre un explorador amigable de cada sesión viva y archivada. Elige una y luego escoge un ritual: - -- **Rejoin** — adjúntate a un PTY vivo y sigue su salida. -- **View log** — abre el registro append-only de eventos. -- **Summon** — restaura una sesión archivada a la lista activa. -- **Archive** — oculta una sesión terminada sin borrar los eventos. -- **Sacrifice** — borra permanentemente una sesión no en ejecución (requiere `--yes`). - -También existen variantes amigables para pipes: `coven sessions --plain` para tablas, `coven sessions --json` para clientes. - -## Configuración (opcional) - -El estado de Coven vive bajo `$COVEN_HOME` (por defecto `~/.coven` en macOS/Linux). El daemon enlaza un socket Unix en `/coven.sock` y rechaza TCP por defecto. - -- Si **no haces nada**, Coven usa tus inicios de sesión locales de harness existentes. -- Si quieres restringirlo, acota `$COVEN_HOME` por raíz de proyecto o por familiar. - -Ejemplo: - -```bash -export COVEN_HOME="$HOME/.local/share/coven" -coven daemon restart -``` - -## Empieza aquí - - - - Topología del runtime, límite de autoridad, ciclo de vida de la sesión y el plano de control. - - - Configuración por harness, límite de auth del proveedor y expectativas del adaptador. - - - API por socket versionada para comux, plugin OpenClaw y tus propios clientes. - - - Archive, summon y sacrifice — los verbos seguros para principiantes alrededor del estado de sesión. - - - Problemas comunes de configuración, variables de entorno y cómo presentar un paquete de diagnósticos. - - - -## Saber más - - - - Límite de autoridad, garantías del almacén, harnesses compatibles y señales del roadmap. - - - Límite de confianza, manejo de secretos, postura del socket y aprobaciones de automatización. - - - Diagnósticos del daemon, pistas de instalación de harness, recuperación de huérfanos y verificación. - - - Milestones actuales, dirección del adaptador y límites del producto público. - - diff --git a/docs/es/install/windows.md b/docs/es/install/windows.md deleted file mode 100644 index 0962abaa..00000000 --- a/docs/es/install/windows.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -summary: "Instala Coven en Windows nativo." -read_when: - - Instalando en Windows -title: "Instalación en Windows" -description: "Instala Coven en Windows: cómo configurar el wrapper, el binario nativo del daemon, COVEN_HOME y las CLIs de harness en un host de Windows o un entorno WSL2." ---- - -# Instalación en Windows - -Usa el wrapper de npm publicado desde PowerShell, Windows Terminal u otro terminal que pueda ejecutar paquetes de Node.js: - -```powershell -npx @opencoven/cli doctor -``` - -Para uso recurrente, instala el wrapper de forma global: - -```powershell -npm install -g @opencoven/cli -coven doctor -``` - -El wrapper expone el comando `coven` y lanza el binario nativo de Windows cuando el paquete de la release incluye uno para tu plataforma. `coven doctor` es el primer paso de verificación: comprueba el estado local e informa de si las CLIs de harness compatibles, como Codex o Claude Code, están disponibles en `PATH`. - -## Primera ejecución - -Desde el directorio de un proyecto: - -```powershell -coven -``` - -El comando por defecto abre la TUI prompt-first. También puedes usar el flujo explícito de CLI: - -```powershell -coven doctor -coven daemon start -coven run codex "fix the failing tests" -coven sessions -``` - -Instala y autentica al menos una CLI de harness antes de esperar que `coven run` lance trabajo. Si `coven doctor` informa de un harness ausente, instala esa herramienta, abre un nuevo terminal para que `PATH` se refresque y ejecuta `coven doctor` de nuevo. - -## Notas sobre Windows - -- Mantén `COVEN_HOME` en una ruta local propiedad de tu usuario de Windows cuando lo sobrescribas. -- Ejecuta Coven y tu CLI de harness desde el mismo entorno. Un harness instalado solo dentro de WSL2 no está disponible para PowerShell nativo de Windows a menos que lo expongas por separado. -- Si la entrada del terminal se comporta de forma extraña, actualiza al wrapper más reciente y ejecuta `coven tui` de nuevo. La TUI de Windows filtra los eventos de pulsación de teclas para que los caracteres tecleados, las flechas y Enter se manejen una sola vez. - -## Relacionado - -- [Empieza con Coven](/GETTING-STARTED) -- [TUI de Coven](/start/coven-tui) -- [Solución de problemas](/TROUBLESHOOTING) -- [Referencia de la CLI](/reference/cli) diff --git a/docs/es/reference/api.md b/docs/es/reference/api.md deleted file mode 100644 index d83822ca..00000000 --- a/docs/es/reference/api.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -summary: "Endpoints actuales de la API por socket local de Coven." -read_when: - - Buscar un endpoint - - Construir un cliente contra `/api/v1` -title: "Referencia de la API de Coven" -description: "Referencia de endpoints para la API por socket local de Coven bajo /api/v1: health, capabilities, actions, sessions, events y reenvío de input." ---- - - -El daemon de Coven expone su API pública como HTTP sobre un socket Unix bajo `/coven.sock`. El contrato activo es **`coven.daemon.v1`** servido bajo `/api/v1`. - -```mermaid -flowchart LR - Root["/api/v1"] --> Version["GET /api-version"] - Root --> Health["GET /health"] - Root --> Capabilities["GET /capabilities"] - Root --> Actions["POST /actions"] - Root --> Sessions["/sessions"] - Root --> Events["GET /events"] - - Sessions --> SList["GET /"] - Sessions --> SCreate["POST /"] - Sessions --> SById["/:id"] - SById --> SGet["GET /"] - SById --> SInput["POST /input"] - SById --> SKill["POST /kill"] -``` - -## Endpoints - -| Método | Ruta | Propósito | Cuerpo | Éxito | Errores | -|---|---|---|---|---|---| -| GET | `/api/v1/api-version` | Versión activa de API + versiones compatibles. | — | `{ apiVersion, supportedApiVersions }` | — | -| GET | `/api/v1/health` | Accesibilidad del daemon, versión, capabilities, pid. | — | `{ ok, apiVersion, covenVersion, capabilities, daemon }` | `503 runtime_unavailable` | -| GET | `/api/v1/capabilities` | Catálogo de capabilities con pistas de política. | — | `{ capabilities: [...] }` | — | -| GET | `/api/v1/capabilities/harnesses` | Agregado de manifiestos de capabilities nativos de harness más skills de Coven (`?refresh=1` re-escanea). | — | `{ coven_skills, harness_capabilities, scanned_at }` | — | -| GET | `/api/v1/capabilities/:harness` | Manifiesto de capabilities de un harness (`?refresh=1` re-escanea). | — | objeto manifiesto | `404 harness_not_found` | -| POST | `/api/v1/actions` | Enrutar un id de acción conocido del plano de control. | `{ action, origin, intentId, args }` | `{ ok, accepted, status, event }` | `400 invalid_request` (acción desconocida) | -| GET | `/api/v1/sessions` | Listar sesiones activas. | — | `SessionRecord[]` | — | -| POST | `/api/v1/sessions` | Lanzar una sesión de harness limitada al proyecto. | `{ projectRoot, cwd?, harness, prompt, title?, launchMode?, conversation?, conversationId? }` | `SessionRecord` | `400 invalid_request` (incluye cwd fuera de proyecto, id de harness desconocido, body mal formado), `500 launch_failed` (runtime spawn / escritura inicial / arranque del CLI falló; fila marcada como `failed`) | -| GET | `/api/v1/sessions/:id` | Obtener una sesión. | — | `SessionRecord` | `404 session_not_found` | -| POST | `/api/v1/sessions/:id/input` | Reenviar input a una sesión viva. | `{ data }` | `{ ok, accepted }` | `400 invalid_request` (body mal formado / `data` ausente o no-string), `404 session_not_found`, `409 session_not_live`, `500 send_input_failed` | -| POST | `/api/v1/sessions/:id/kill` | Matar una sesión viva. | — | `{ ok, accepted }` | `404 session_not_found`, `409 session_not_live`, `500 kill_failed` | -| GET | `/api/v1/events` | Leer eventos de sesión paginados. | — (`?sessionId`, `?afterSeq`, `?afterEventId`, `?limit`) | `{ events, nextCursor, hasMore }` | `400 invalid_request` | - -Todas las respuestas de error usan el sobre estructurado documentado en [Contrato de la API](/API-CONTRACT#structured-error-envelope). - -## Siempre empieza con health - -```http -GET /api/v1/health -``` - -La respuesta te indica la `apiVersion` activa, las `capabilities` del daemon y el pid/uptime en ejecución. Trata el resto de la API como indefinido hasta que hayas leído esos campos. - -Consulta [API local de Coven](/API) para ejemplos de respuesta y [Contrato de la API](/API-CONTRACT) para las formas estables y los sobres de fallo. - -## Relacionado - -- [API local de Coven](/API) -- [Contrato de la API](/API-CONTRACT) -- [Autenticación y acceso local](/AUTH) -- [Integración de clientes](/CLIENT-INTEGRATION) diff --git a/docs/es/reference/cli.md b/docs/es/reference/cli.md deleted file mode 100644 index 495d17c2..00000000 --- a/docs/es/reference/cli.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -summary: "Superficie actual de comandos de la CLI de Coven." -read_when: - - Buscar una flag de la CLI de Coven - - Programar scripts contra la CLI de Coven -title: "Referencia de la CLI de Coven" -description: "Referencia de los comandos de la CLI coven: doctor, daemon, run, sessions, attach, archive, kill, summon, sacrifice, view y flags de la TUI." ---- - - -El comando orientado al usuario es siempre `coven`. Los paquetes wrapper como `@opencoven/cli`, `@opencoven/cli-macos` y `@opencoven/cli-linux-x64` instalan el mismo binario. - -```mermaid -flowchart TB - Root["coven"] --> TUI["tui (default)"] - Root --> Doctor["doctor"] - Root --> Daemon["daemon"] - Root --> Run["run"] - Root --> Sessions["sessions"] - Root --> Attach["attach"] - Root --> Summon["summon"] - Root --> Archive["archive"] - Root --> Sacrifice["sacrifice"] - Root --> Patch["patch"] - Root --> Pc["pc (macOS-first)"] - - Daemon --> DStart["start"] - Daemon --> DStatus["status"] - Daemon --> DRestart["restart"] - Daemon --> DStop["stop"] - - Run --> RCodex["codex <prompt>"] - Run --> RClaude["claude <prompt>"] - - Sessions --> SPlain["--plain"] - Sessions --> SJson["--json"] - Sessions --> SAll["--all"] - Sessions --> SManage["--manage"] - - Patch --> POpenclaw["openclaw <prompt>"] - - Pc --> PcStatus["status [--json]"] - Pc --> PcTop["top --n N"] - Pc --> PcDisk["disk"] - Pc --> PcKill["kill <pid> --confirm"] - Pc --> PcCache["cache clear --confirm"] -``` - -## Nivel superior - -| Comando | Acción | -|---|---| -| `coven` | Abre el menú interactivo amigable para principiantes. | -| `coven tui` | Abre explícitamente la TUI de comandos slash. | -| `coven doctor` | Detecta las CLIs de harness compatibles e imprime pistas de instalación. | -| `coven daemon start/status/restart/stop` | Gestiona el daemon local. | -| `coven run ` | Lanza una sesión de harness limitada al proyecto. Ids de harness actuales: `codex`, `claude`. | -| `coven sessions` | Abre el explorador de sesiones; soporta `--plain`, `--json`, `--all` y `--manage`. | -| `coven attach ` | Reproduce/sigue la salida de la sesión y reenvía input cuando esté viva. | -| `coven summon ` | Restaura una sesión archivada y luego la reproduce/sigue. | -| `coven archive ` | Oculta una sesión no en ejecución preservando los eventos. | -| `coven sacrifice --yes` | Borra permanentemente una sesión no en ejecución. | -| `coven patch openclaw ` | Bucle de rescate local de OpenClaw. No hace commit ni push. | -| `coven pc` | Diagnóstico primero para macOS y operaciones de relief con `--confirm` explícito. | - -## Flags comunes por comando - -| Comando | Flags | -|---|---| -| `coven run` | `--cwd `, `--title `, `--json`, `--detach` | -| `coven sessions` | `--plain`, `--json`, `--all`, `--manage` | -| `coven attach` | `--follow` (por defecto), `--no-follow` (solo replay) | -| `coven sacrifice` | `--yes` (requerido) | -| `coven daemon start` | `--coven-home ` (sobrescribe `$COVEN_HOME`) | -| `coven pc kill` | `--confirm` (requerido) | -| `coven pc cache clear` | `--confirm` (requerido) | -| `coven pc top` | `--n `, `--verbose` | -| `coven pc status` | `--json` | - -## Convenciones de flags - -- **Comandos limitados al proyecto** aceptan `--cwd ` para un directorio de lanzamiento dentro de la raíz de proyecto. -- **Comandos amigables para pipes** aceptan `--plain` para tablas y `--json` para salida de máquina. -- **Comandos destructivos** requieren `--yes` (o `--confirm` para relief de `coven pc`). -- **Comandos que tocan el daemon** imprimen pistas de instalación/reparación cuando el socket falta. - -## Códigos de salida - -| Código | Significado | -|---|---| -| `0` | Éxito. | -| `1` | Error genérico de CLI (argv erróneo, subcomando desconocido). | -| `2` | Error de validación (cwd fuera de raíz, id de harness desconocido). | -| `3` | Daemon no disponible (socket faltante o no saludable). | -| `4` | Acción destructiva rechazada (falta `--yes` / `--confirm`, o el objetivo está vivo). | -| `>=10` | Reservado para futuros códigos de salida estructurados; las builds actuales pueden no emitirlos aún. | - -El comando `coven attach` sale con el código de salida de la sesión subyacente cuando la sesión ya no está viva, así los scripts pueden encadenar `coven run … && coven attach ` y observar el propio estado del harness. - -## Relacionado - -- [Empezar](/GETTING-STARTED) -- [TUI de Coven](/start/coven-tui) -- [Ciclo de vida de la sesión](/SESSION-LIFECYCLE) -- [Guía de adaptadores de harness](/HARNESS-ADAPTERS) -- [Solución de problemas](/TROUBLESHOOTING) diff --git a/docs/es/reference/release-notes.md b/docs/es/reference/release-notes.md deleted file mode 100644 index 2210e610..00000000 --- a/docs/es/reference/release-notes.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -summary: "Notas por release del runtime, la CLI y la API local de Coven." -description: "Notas de release semanales de Coven con nuevas funcionalidades, correcciones y cambios incompatibles del runtime, la CLI, la TUI y la API por socket local." -read_when: - - Looking up what changed -title: "Changelog y notas de release de Coven" ---- - -## Semana del 14 de julio de 2026 - -### Nuevas funcionalidades - -- **GitHub Copilot CLI es un harness integrado soportado (v0.0.54).** `coven run copilot "…"` ahora lanza la GitHub Copilot CLI (`npm install -g @github/copilot`) bajo la misma supervisión PTY anclada al proyecto que Codex y Claude Code. `--permission full|read-only` se mapea a los flags nativos de Copilot (`--allow-all` / `--deny-tool write --deny-tool shell`), `--model`, `--add-dir` y `--think`/`--speed` (vía `--effort`) se reenvían de forma nativa, y `coven chat` mantiene conversaciones entre turnos mediante UUIDs preasignados con `--session-id`. Consulta [Harness de Copilot CLI](/harnesses/copilot-cli) y el [issue #381](https://github.com/OpenCoven/coven/issues/381). - -## Semana del 4 de julio de 2026 - -### Actualizaciones - -- **Selección de modelo sólo por login de CLI (v0.0.53).** La documentación de selección de modelo ahora muestra únicamente las rutas soportadas de Codex CLI y Claude Code. Se quitaron de la superficie seleccionable `/models` las páginas de opciones por proveedor/API key para OpenAI, Anthropic, Google y backends de modelos locales, de modo que clientes y usuarios vayan por `codex login` o `claude doctor` en lugar de credenciales crudas de proveedor. Consulta [Model selection](/models). - -## Semana del 24 de junio de 2026 - -### Nuevas funcionalidades - -- **Wrapper de npm external OpenClaw bridge plugin copublicado (v0.0.49).** El pipeline de release ahora publica un segundo nombre de wrapper, external OpenClaw bridge plugin, junto con `@opencoven/cli`. Ambos wrappers dependen de los mismos paquetes nativos `@opencoven/cli-*`, así que instalar cualquiera de los dos termina en el mismo binario `coven`. Esto permite que docs y onboarding anuncien el nombre canónico *coven* sin romper instalaciones existentes de `@opencoven/cli`. Consulta [PR #257](https://github.com/OpenCoven/coven/pull/257) y el [runbook de releasing](/reference/releasing) para la configuración única de Trusted Publisher que necesita el paquete nuevo antes de su primer release OIDC. -- **Spec de Coven Group Chat (v0.0.49).** Se añadió el diseño v1 para una primitiva de chat grupal del lado del servidor en `specs/coven-group-chat/` (PRODUCT + TECH). Hoy el chat grupal sólo existe como una ilusión de fan-out en el cliente iOS; el spec define un objeto de servidor durable y sincronizado, con ordenación monótona de eventos para que iOS, web y CLI lean el mismo grupo. La implementación se rastrea por separado. Consulta [PR #258](https://github.com/OpenCoven/coven/pull/258). - -### Actualizaciones - -- **Referencias a OpenMeow eliminadas en docs y código (v0.0.49).** OpenMeow no es una aplicación de OpenCoven — CastCodes es el cliente canónico. Ejemplos y etiquetas sueltas de OpenMeow en docs en inglés/español/ruso, `DESIGN.md`, `ARCHITECTURE.md`, `AUTH.md`, `API-CONTRACT.md` y referencias relacionadas se reescribieron en lenguaje neutro al producto. `crates/coven-cli/src/api.rs` renombra el origen de prueba `openmeow` a `external-client`, y `skills/coven-task-manager` elimina `openmeow` de la lista de etiquetas de repo reconocidas. No hay cambios de comportamiento en runtime. Consulta [PR #256](https://github.com/OpenCoven/coven/pull/256). - -## Semana del 18 de junio de 2026 - -### Nuevas funcionalidades - -- **Controles de razonamiento para `coven run` (v0.0.48).** `coven run` ahora acepta `--think` y `--speed fast|balanced|thorough` junto con `--model`. Los lanzamientos de Claude traducen esos hints a `--effort`; los harnesses sin soporte avisan y continúan en vez de fallar. Consulta [issue #246](https://github.com/OpenCoven/coven/issues/246), [PR #254](https://github.com/OpenCoven/coven/pull/254) y [referencia de `coven run`](/reference/cli-run). -- **Receta confiable del adaptador Hermes (v0.0.41).** `coven adapter install hermes` ahora escribe un manifiesto confiable local bajo `COVEN_HOME/adapters/hermes.json`, y Coven carga automáticamente manifiestos desde ese trust store propio. Los usuarios nuevos ya no necesitan escribir JSON a mano ni configurar `COVEN_HARNESS_ADAPTER_MANIFEST` solo para probar Hermes. - -### Actualizaciones - -- **Estado del paquete Windows x64.** El README público ahora refleja que `@opencoven/cli-windows` ya está publicado, no en staging. En Windows se puede instalar con el wrapper universal `@opencoven/cli` y verificar los harnesses locales con `coven doctor`. - -### Correcciones de errores - -- **Backfill resiliente del índice FTS de eventos (v0.0.48).** El backfill de eventos existentes hacia `events_fts` ahora corre en lotes acotados, registra su finalización en `store_meta`, aplica `busy_timeout` a conexiones de lectura y trata `SQLITE_BUSY` como no fatal, de modo que la indexación de búsqueda no bloquea todos los lanzamientos de agentes en historiales grandes. Consulta [issue #249](https://github.com/OpenCoven/coven/issues/249) y [PR #254](https://github.com/OpenCoven/coven/pull/254). -- **Guía más clara para harnesses no soportados.** Los errores de harness desconocido ahora muestran los IDs configurados y orientan a usuarios de Hermes hacia `coven adapter install hermes` seguido de `coven adapter doctor hermes`. -- **Fallback de directorio home en Windows.** `coven doctor` y la resolución del store funcionan en PowerShell cuando `HOME` no existe, probando `USERPROFILE`, `HOMEDRIVE` + `HOMEPATH` y el home de la plataforma antes de pedir `COVEN_HOME`. - -## Semana del 3 de junio de 2026 - -### Nuevas funcionalidades - -- **Protocolo de trabajo paralelo de Coven.** Coven ahora incluye comandos `coven wt`, `coven claim` y `coven hooks` para coordinar varios agentes de programación de IA en un mismo repositorio. El protocolo crea worktrees de git aislados, registra claims de rama con TTL, instala hooks encadenables de seguridad, bloquea commits accidentales en ramas protegidas y exige una frase explícita de intención de merge antes de pushes a ramas protegidas. Consulta [issue #167](https://github.com/OpenCoven/coven/issues/167) y [PR #169](https://github.com/OpenCoven/coven/pull/169). -- **Persistencia de identidad familiar en sesiones.** Las sesiones ahora pueden llevar un `familiar_id` resuelto, dando a dashboards, APIs y superficies de agentes una forma durable de mostrar qué familiar inició o posee una sesión. Consulta [PR #168](https://github.com/OpenCoven/coven/pull/168). - -### Actualizaciones - -- **Resolución compartida de familiares.** La CLI, el daemon y la API local ahora resuelven identidades familiares por una única ruta compartida antes del lanzamiento, de modo que los metadatos guardados de sesión reflejan la identidad familiar canónica y no una cadena de entrada sin validar. -- **Guardrails para carriles paralelos.** El protocolo de worktrees incluye superficies de status, doctor, prune, claim acquire/release/heartbeat/canary e instalación de hooks para que la coordinación entre agentes pueda escalar sin depender de scripts shell ad hoc. - -### Correcciones de errores - -- **Los IDs de familiar desconocidos ya no crean sesiones.** `POST /sessions` ahora rechaza un `familiarId` desconocido con `400 unknown_familiar` antes de insertar una fila de sesión o lanzar un runtime. Una configuración de familiares mal formada devuelve `500 familiar_lookup_failed` sin lanzar nada. -- **`coven run --familiar ` falla temprano con familiares desconocidos.** Los lanzamientos locales por CLI ahora coinciden con el comportamiento del daemon/API y evitan guardar IDs de familiar no resueltos. - -## Semana del 17 de mayo de 2026 - -### Correcciones de errores - -- **Se acabaron las pulsaciones dobles en la TUI de Windows.** `coven tui` y el navegador de sesiones ahora filtran únicamente los eventos de pulsación de tecla en Windows, de modo que escribir `a` ya no inserta `aa`, las flechas avanzan una fila por pulsación y Enter activa la selección una sola vez. No hay cambios de comportamiento en macOS ni en Linux. Consulta [Coven TUI](/start/coven-tui) e [Instalación en Windows](/install/windows). -- **La TUI ya no se cae en terminales pequeñas.** Tanto `coven tui` como `coven chat` ahora protegen sus cálculos de layout frente a tamaños de terminal muy pequeños, de modo que redimensionar a una ventana estrecha o baja ya no provoca el cierre de la sesión. Consulta [Coven TUI](/start/coven-tui). -- **Higiene de gates de release.** El guard de secretos de release pública ahora permite URLs públicas de avisos de GitHub y escanea el historial de release desde `HEAD`, para que ramas remotas obsoletas no bloqueen el gate actual. - -### Seguridad - -- **Aviso de seguridad de Ratatui resuelto.** Se actualizó la pila de renderizado de Ratatui para incorporar la versión parcheada del crate `lru`, resolviendo el aviso [GHSA-rhfx-m35p-ff5j](https://github.com/advisories/GHSA-rhfx-m35p-ff5j). No se requiere ninguna acción: basta con instalar la última versión. - -## Semana del 15 de mayo de 2026 - -### Actualizaciones - -- **Tema TUI alineado con la marca.** Tanto `coven tui` como `coven chat` ahora comparten una paleta unificada y alineada con la marca, con tokens semánticos consistentes para los estilos primary, agent, user, hint, surface y dim. Los colores se adaptan a tu terminal automáticamente: truecolor en terminales de 24 bits, 256 colores en terminales legacy, y sin color cuando la salida está canalizada o `NO_COLOR` está configurado. Consulta [Troubleshooting](/TROUBLESHOOTING). - -## Cómo leer este changelog - -```mermaid -flowchart LR - Week["Entrada semanal\n(YYYY-MM-DD)"] --> New["### Nuevas funcionalidades"] - Week --> Upd["### Actualizaciones"] - Week --> Fix["### Correcciones de errores"] - Week --> Sec["### Seguridad (cuando aplique)"] - - New --> Links["Cada elemento enlaza al documento canónico o al PR"] - Upd --> Links - Fix --> Links - Sec --> Links -``` - -Las entradas son semanales, primero las más recientes. Los elementos dentro de cada semana se agrupan por categoría. Cualquier cambio que afecte a la API pública (superficie de la CLI, rutas del socket, formas de respuesta) también aparece en [Contrato de la API](/API-CONTRACT) — el changelog es un puntero, no un sustituto. - -## Semana del 11 de mayo de 2026 - -### Nuevas funcionalidades - -- **TUI de Coven orientada a prompts.** Ejecutar `coven` (o `coven tui`) ahora abre una interfaz interactiva basada en Ratatui. Escribe tareas en formato libre, ejecuta slash commands (`/help`, `/agent`, `/clear`, `/export`, `/exit`) y navega por los menús de rituales con las teclas de flecha. Funciona sobre SSH y se redimensiona de forma segura. Consulta [Coven TUI](/start/coven-tui). -- **Diagnóstico y alivio con `coven pc`.** Una herramienta de presión del sistema orientada primero a macOS. Los comandos de solo lectura muestran instantáneas de CPU, memoria, disco y procesos principales; las operaciones de escritura (`coven pc kill`, `coven pc cache clear`) requieren una puerta `--confirm` explícita. Consulta la [referencia de la CLI](/reference/cli) y [Troubleshooting](/TROUBLESHOOTING). -- **Contrato de la API local v1.** La API por socket del daemon ahora expone endpoints versionados de salud y capacidades, respuestas de error estructuradas y paginación de eventos basada en cursor. Los clientes pueden negociar funcionalidades en lugar de adivinar. Consulta [Contrato de la API](/API-CONTRACT) y [API local](/API). -- **Salida JSON de sesiones.** `coven sessions --json` emite listados de sesiones legibles por máquina para scripts, dashboards y clientes externos. Consulta [comux JSON sessions](/sessions/comux-json). -- **Ruta de instalación en Windows.** Coven ahora distribuye un paquete npm para Windows, de modo que `npx @opencoven/cli` funciona en Windows nativo junto con macOS y Linux. Consulta [Getting started](/GETTING-STARTED). - -### Actualizaciones - -- **Posicionamiento y marca de OpenCoven.** Se refrescó la copia de producto en la documentación y la CLI para enmarcar a Coven como un ecosistema de familiares de IA persistentes, con tokens de marca y guía de diseño actualizados. Consulta [Marca](/BRAND). -- **Paleta de marca refinada.** Se actualizó la paleta de OpenCoven a un gris lavanda apagado (`#9A8ECD`) con un nuevo sistema de acentos complementarios y tokens de superficie dedicados para modo claro y oscuro. Se preservan los alias de color legacy existentes, así que no se requiere ninguna acción para adoptar la nueva apariencia. Consulta [Marca](/BRAND). -- **Tema TUI alineado con la marca.** La TUI de Coven ahora utiliza un tema unificado alineado con la paleta de OpenCoven. Los fallbacks elegantes para terminales sin color, de 256 colores y truecolor mantienen su legibilidad localmente, sobre SSH y dentro de CI. Consulta [Coven TUI](/start/coven-tui). -- **Troubleshooting: salud y presión del sistema.** Se añadió una sección que enlaza desde el flujo canónico de troubleshooting a `coven pc` para diagnosticar presión local de CPU, memoria y disco. Consulta [Troubleshooting](/TROUBLESHOOTING). -- **IDs completos de sesión en la salida plain.** `coven sessions --plain` ahora imprime los IDs completos de sesión para que puedan copiarse directamente a comandos posteriores. - -### Correcciones de errores - -- **Verificación del estado del daemon.** `coven` ahora verifica el daemon a través de su socket de salud antes de reportar `running`, limpia los metadatos obsoletos muertos y reporta `stale` cuando los metadatos están vivos pero no verificados. -- **Recuperación de metadatos corruptos del daemon.** La CLI ahora se recupera de forma elegante cuando los metadatos del estado del daemon en disco están corruptos, en lugar de fallar al arrancar. -- **Paginación de eventos más estricta.** La API rechaza los valores no enteros de `limit` y `afterSeq` con un error estructurado `invalid_request` antes de hacer cualquier búsqueda de sesión. -- **Falsos positivos del guard de secretos de release.** El guard de secretos de release pública ahora permite los enlaces documentados del repositorio de OpenCoven y las rutas locales de worktree como tokens benignos de alta entropía, mientras sigue marcando los patrones de secretos explícitos. diff --git a/docs/es/reference/releasing.md b/docs/es/reference/releasing.md deleted file mode 100644 index 68e3f12c..00000000 --- a/docs/es/reference/releasing.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -summary: "Flujo de release para @opencoven/cli y los paquetes de plataforma." -read_when: - - Cutting a release -title: "Publicando releases" -description: "Runbook para operadores: cómo publicar Coven en npm con preflight, dry-run, publicación del wrapper de CLI y los paquetes nativos, y verificación postflight." ---- - -Coven publica el wrapper de npm y los paquetes nativos de plataforma desde el workflow de GitHub Actions **Release npm packages**. Las versiones del paquete fuente permanecen en `0.0.0`; la versión del dispatch del workflow es la versión publicada en npm. - -## Preflight - -Antes de publicar: - -1. Confirma que no hay PRs abiertos que deban entrar en la release. -2. Confirma que el CI de `main` está en verde para el commit exacto que vas a publicar. -3. Comprueba en npm las versiones actuales de `latest`: - -```sh -npm view @opencoven/cli version dist-tags -npm view @opencoven/cli-macos version dist-tags -npm view @opencoven/cli-linux-x64 version dist-tags -npm view @opencoven/cli-windows version dist-tags -``` - -4. Confirma que el changelog, la copia de estado del README del paquete y los recursos de marca coinciden con la release. - -## Dry Run - -Ejecuta primero el workflow con `publish=false`. Esto construye todos los binarios de plataforma y realiza dry-runs de npm publish sin necesidad de credenciales de npm: - -```sh -gh workflow run release-npm.yml \ - --ref main \ - -f publish=false \ - -f version=0.0.13 -``` - -Observa la ejecución: - -```sh -gh run list --workflow release-npm.yml --branch main --limit 1 -gh run watch -``` - -## Publish - -Publica solo después de que el dry-run tenga éxito y las versiones de los paquetes npm sigan disponibles: - -```sh -gh workflow run release-npm.yml \ - --ref main \ - -f publish=true \ - -f version=0.0.13 -``` - -El job de publish usa el entorno `npm-publish` y `NPM_ACCESS_TOKEN`. Publica primero los paquetes nativos (`@opencoven/cli-linux-x64`, `@opencoven/cli-windows`, `@opencoven/cli-macos`) y luego el paquete wrapper (`@opencoven/cli`). - -## Postflight - -Después de que la ejecución de publish se complete: - -```sh -npm view @opencoven/cli version dist-tags -npm view @opencoven/cli-macos version dist-tags -npm view @opencoven/cli-linux-x64 version dist-tags -npm view @opencoven/cli-windows version dist-tags -``` - -Si algún paquete no se publicó, no vuelvas a ejecutar a ciegas. Inspecciona el job fallido, confirma qué versiones de paquete existen en npm y vuelve a ejecutar solo con una nueva versión si npm ya ha aceptado parte de la release. diff --git a/docs/es/start/coven-tui.md b/docs/es/start/coven-tui.md deleted file mode 100644 index e0bdf151..00000000 --- a/docs/es/start/coven-tui.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -summary: "El menú interactivo prompt-first lanzado por `coven` o `coven tui`." -read_when: - - Explorar qué puede hacer el menú interactivo de Coven - - Aprender comandos slash y atajos - - Decidir si usar la TUI o los verbos de CLI de bajo nivel -title: "TUI de Coven" -description: "Usa la TUI prompt-first de Coven para lanzar sesiones de harness, navegar trabajo en ejecución, adjuntarte a sesiones y disparar rituales desde un solo menú." ---- - -`coven` (o el explícito `coven tui`) abre la **TUI prompt-first**: una interfaz respaldada por Ratatui donde puedes escribir tareas en forma libre, ejecutar comandos slash o navegar menús de rituales con las teclas de flecha. Es el punto de partida recomendado para usuarios nuevos y funciona sobre SSH o en un terminal local. - -## Cuándo usarla - -| Situación | Mejor superficie | -|---|---| -| Instalación recién hecha, explorando lo que Coven puede hacer | **TUI** (`coven`) | -| Tarea puntual en un proyecto conocido | **TUI** o `coven run ""` | -| Scripting, pipes, salida legible por máquina | `coven sessions --json`, `--plain` | -| Attach/replay de larga duración | Explorador de sesiones de la TUI o `coven attach ` | -| Comprobación rápida de salud | `coven doctor` | - -La TUI es una capa fina de presentación. Cada acción que ofrece se mapea a un verbo subyacente de CLI o llamada a la API por socket — el daemon en Rust sigue siendo la autoridad. - -## Anatomía - -```mermaid -flowchart TB - subgraph TUI["coven TUI"] - Input["Prompt-first input bar\n(free text + slash commands)"] - Browser["Session browser pane"] - Help["Help / shortcuts overlay"] - end - Input -->|free text| LaunchPath["coven run "] - Input -->|slash command| Dispatch["/run, /sessions, /archive, ..."] - Browser -->|Rejoin| Attach["coven attach"] - Browser -->|Archive| Archive["coven archive"] - Browser -->|Summon| Summon["coven summon"] - Browser -->|Sacrifice| Sacrifice["coven sacrifice"] - LaunchPath --> Daemon[Coven daemon] - Dispatch --> Daemon - Attach --> Daemon - Archive --> Daemon - Summon --> Daemon - Sacrifice --> Daemon -``` - -La TUI nunca se salta el daemon. La raíz de proyecto, el cwd y el id de harness se revalidan del lado del servidor en cada lanzamiento. - -## Modos de input - -La barra de prompt acepta tres formas de input indistintamente: - -1. **Texto libre de tarea** — cualquier cosa que **no** empiece con `/`. Pulsar `Enter` lanza el harness por defecto contra el proyecto actual. - - ```text - fix the failing tests - review the diff in packages/cli - ``` - -2. **Comandos slash** — empiezan con `/` y se enrutan a un verbo específico. - - ```text - /run codex "audit this repo" - /run claude "polish the help text" --title "Help polish" - /sessions - /archive session-1 - /help - ``` - -3. **Navegación por menú con teclas de flecha** — `↑` / `↓` recorren cards de ritual (Rejoin, View Log, Summon, Archive, Sacrifice) para la sesión actualmente seleccionada. `Enter` confirma. `Esc` cancela. - -## Referencia de comandos slash - -| Comando | Qué hace | -|---|---| -| `/help` | Muestra el overlay de ayuda con todos los atajos y ejemplos. | -| `/run ""` | Lanza una sesión limitada al proyecto. Igual que `coven run`. | -| `/sessions` | Abre el explorador de sesiones. Igual que `coven sessions`. | -| `/attach ` | Adjunta a (o reproduce) una sesión. | -| `/archive ` | Oculta una sesión no en ejecución preservando los eventos. | -| `/summon ` | Restaura una sesión archivada. | -| `/sacrifice ` | Borra permanentemente una sesión no en ejecución. Te pide que escribas `sacrifice` para confirmar. | -| `/doctor` | Ejecuta `coven doctor` y renderiza el resultado en línea. | -| `/clear` | Limpia la barra de input y cualquier salida en línea. | -| `/export` | Copia el registro de la sesión seleccionada actual como JSON al portapapeles. | -| `/agent ` | Establece el harness por defecto para el input libre en esta sesión de la TUI. | -| `/exit` | Cierra la TUI limpiamente. Equivalente a `Ctrl+C` o `Esc` en la raíz. | - -## Atajos de teclado - -| Teclas | Acción | -|---|---| -| `h` (raíz) | Abre el overlay `/help` | -| `↑ / ↓` | Mueve la selección en el explorador de sesiones o el menú | -| `Enter` | Confirma la selección / envía el prompt | -| `Esc` | Sale de un menú, o sale en la raíz | -| `Ctrl+C` | Sale inmediatamente | -| `Tab` | Cicla el foco entre la barra de input y el explorador de sesiones | -| `Ctrl+L` | Re-renderiza (útil sobre SSH inestable) | - -La TUI redimensiona de forma segura. Terminales tan pequeños como 80×24 siguen siendo usables; los terminales más anchos expanden la lista de sesiones, la vista previa del log y el overlay de ayuda automáticamente. - -## Acciones del explorador de sesiones - -Seleccionar una sesión y pulsar `Enter` muestra acciones contextuales. Cada una está restringida por el estado de la sesión — las acciones que no son seguras para el estado actual se ocultan, no se ponen en gris, así que el menú nunca ofrece un verbo destructivo que no puedas ejecutar. - -| Acción | Disponible cuando | Efecto | -|---|---|---| -| **Rejoin** | la sesión está `running` | Adjunta al PTY vivo; el input se reenvía al harness. | -| **View Log** | la sesión no está `running` | Reproduce el log de eventos (solo lectura). | -| **Summon** | `archived_at` está establecido | Restaura a la lista activa y reproduce/sigue. | -| **Archive** | la sesión no está `running` y no archivada | Oculta de la lista activa; los eventos se preservan. | -| **Sacrifice** | la sesión no está `running` | Borrado permanente; requiere confirmación tecleada. | - -El mapa entre acciones y verbos de CLI está documentado en [Ciclo de vida de la sesión](/SESSION-LIFECYCLE). - -## Uso por SSH y remoto - -La TUI está basada en Ratatui y sobrevive a los entornos hostiles habituales: - -- Terminales sobre SSH (sin dependencias locales de ratón/fuente). -- Redimensionado durante una sesión (re-renderiza en `SIGWINCH`). -- `TERM=xterm-256color` o `screen-256color`. - -**No** requiere un terminal gráfico, un backend de portapapeles o `tmux`. Si estás dentro de `tmux` o `screen`, la TUI se comporta como cualquier otra app Ratatui — los splits de panel y detach siguen funcionando. - -## Fallback en texto plano - -Si prefieres un flujo no interactivo (CI, scripting, logs de auditoría), sáltate la TUI por completo: - -```bash -coven run codex "fix the failing tests" -coven sessions --plain -coven attach -``` - -Estos verbos producen salida estable y scriptable, y son los mismos a los que la TUI termina enrutando. - - - -## Relacionado - -- [Empieza con Coven](/GETTING-STARTED) -- [Ciclo de vida de la sesión](/SESSION-LIFECYCLE) -- [Referencia de la CLI](/reference/cli) -- [Solución de problemas](/TROUBLESHOOTING) diff --git a/docs/es/superpowers/plans/2026-05-15-tui-chat-module.md b/docs/es/superpowers/plans/2026-05-15-tui-chat-module.md deleted file mode 100644 index 5ef7fe1a..00000000 --- a/docs/es/superpowers/plans/2026-05-15-tui-chat-module.md +++ /dev/null @@ -1,655 +0,0 @@ ---- -title: "Plan de implementación: módulo de chat TUI en coven-cli" -description: "Plan en español para extraer chat.rs (1111 líneas) en un módulo tui/ dentro de coven-cli en tres commits, sin cambios de comportamiento ni nuevas dependencias." ---- - -# Plan de implementación de la extracción del módulo de chat TUI - -> **Para trabajadores agénticos:** SUBHABILIDAD REQUERIDA: Usa superpowers:subagent-driven-development (recomendado) o superpowers:executing-plans para implementar este plan tarea por tarea. Los pasos usan sintaxis de checkbox (`- [ ]`) para el seguimiento. - -**Objetivo:** Dividir `crates/coven-cli/src/chat.rs` (1111 líneas) en un módulo de 4 archivos bajo un nuevo espacio de nombres `tui/`, con cero cambios de comportamiento. - -**Arquitectura:** Movimiento puro de código. Tres commits secuenciales: (1) andamiar archivos nuevos vacíos + cablear `mod tui;` en main.rs, (2) mover todo el contenido desde `chat.rs` hacia los nuevos archivos mientras se hace de `chat.rs` un shim de reexportación, (3) eliminar `chat.rs` + la salvaguarda y actualizar el callsite de `main.rs`. - -**Stack tecnológico:** Rust edición 2021. Sin nuevas dependencias. Las mismas ratatui 0.30 / crossterm 0.29 que en la Fase 1. - -**Especificación:** [`docs/superpowers/specs/2026-05-15-tui-chat-module-design.md`](../specs/2026-05-15-tui-chat-module-design.md) - -**Rama:** `feat/tui-chat-module`, apilada sobre `feat/tui-theme-module`. El PR no puede fusionarse hasta que aterrice #56. - -**Worktree:** `/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module` - ---- - -## Mapa de archivos - -| Archivo | Acción | Notas | -|---|---|---| -| `crates/coven-cli/src/tui/mod.rs` | **Crear** (~10 líneas) | Doc a nivel de módulo + `pub mod chat;` | -| `crates/coven-cli/src/tui/chat/mod.rs` | **Crear** (~40 líneas) | `pub fn run_chat` + reexportaciones de `MessageRole`/`ChatMessage`/`AgentInfo` | -| `crates/coven-cli/src/tui/chat/app.rs` | **Crear** (~530 líneas) | Todo el estado, comportamiento, helpers, tests | -| `crates/coven-cli/src/tui/chat/render.rs` | **Crear** (~380 líneas) | Las 7 funciones `render_*` | -| `crates/coven-cli/src/tui/chat/events.rs` | **Crear** (~150 líneas) | `run_event_loop` | -| `crates/coven-cli/src/chat.rs` | **Eliminar** (actualmente 1111 líneas) | Reemplazado por el módulo de arriba | -| `crates/coven-cli/src/main.rs` | **Modificar** (~2 líneas) | `mod chat;` → `mod tui;` (reordenamiento alfabético); `chat::run_chat()` → `tui::chat::run_chat()` | - -Ningún otro archivo cambia. No se añaden tests; se elimina uno (la salvaguarda). - ---- - -## Nota crítica sobre el directorio de trabajo - -TODOS los comandos `cd`, `cargo` y `git` de este plan se ejecutan desde: - -``` -/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -``` - -La primera acción de cada tarea es hacer `cd` allí y verificar que `git rev-parse --abbrev-ref HEAD` es `feat/tui-chat-module`. De lo contrario PARAR y reportar BLOQUEADO. (Esta es la lección de la Fase 1, donde algunos subagentes implementadores escribieron en el checkout principal por accidente.) - ---- - -## Tarea 1: Andamiar la nueva estructura del módulo - -Crear archivos vacíos/esqueleto para el nuevo módulo y cablearlo en `main.rs`. Tras esta tarea, tanto `mod chat;` (apuntando al viejo `chat.rs`) como `mod tui;` (apuntando al nuevo módulo casi vacío) coexisten. La build pasa con advertencias sobre elementos no usados en los archivos nuevos. - -**Archivos:** -- Crear: `crates/coven-cli/src/tui/mod.rs` -- Crear: `crates/coven-cli/src/tui/chat/mod.rs` -- Crear: `crates/coven-cli/src/tui/chat/app.rs` -- Crear: `crates/coven-cli/src/tui/chat/render.rs` -- Crear: `crates/coven-cli/src/tui/chat/events.rs` -- Modificar: `crates/coven-cli/src/main.rs` (añadir la declaración `mod tui;`) - -- [ ] **Paso 1: cd al worktree y verificar la rama** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -pwd -git rev-parse --abbrev-ref HEAD -``` - -Esperado: -``` -/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -feat/tui-chat-module -``` - -Si alguno difiere, PARAR y reportar BLOQUEADO. No modificar archivos fuera de este worktree. - -- [ ] **Paso 2: Crear `crates/coven-cli/src/tui/mod.rs`** - -Escribir este contenido exacto: - -```rust -//! TUI surfaces for the coven CLI. Currently hosts the chat module; Phases 3–4 -//! will land the launcher and session-browser carve-outs from main.rs here. - -pub mod chat; -``` - -- [ ] **Paso 3: Crear `crates/coven-cli/src/tui/chat/mod.rs` como un stub temporal** - -Este archivo es un stub para la Tarea 1. Se rellenará con `run_chat` y las reexportaciones en la Tarea 2. Por ahora debe compilar sin advertencias aunque nada referencie sus submódulos todavía. - -Escribir este contenido exacto: - -```rust -//! Ratatui-based chat TUI. State lives in `app`, view in `render`, event loop -//! in `events`. The entry point `run_chat` here manages the raw-terminal -//! lifecycle. - -#![allow(dead_code)] - -mod app; -mod events; -mod render; -``` - -El `#![allow(dead_code)]` es temporal — se elimina en el Paso 5 de la Tarea 2 cuando `run_chat` aterrice aquí y consuma los submódulos. Los submódulos se declaran privados (`mod`, no `pub mod`) porque ningún código fuera de `tui::chat` necesita acceder a `tui::chat::app::*`. - -- [ ] **Paso 4: Crear tres archivos de submódulo vacíos** - -Cada uno debe ser Rust válido que compile por sí solo. Escribir cada archivo con solo un comentario de documentación y una línea `// placeholder` (reemplazada en la Tarea 2): - -**`crates/coven-cli/src/tui/chat/app.rs`:** - -```rust -//! Chat application state, behavior, and tests. Populated in Task 2 of the -//! chat-module carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -**`crates/coven-cli/src/tui/chat/render.rs`:** - -```rust -//! Chat TUI render functions. Populated in Task 2 of the chat-module -//! carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -**`crates/coven-cli/src/tui/chat/events.rs`:** - -```rust -//! Chat TUI event loop. Populated in Task 2 of the chat-module -//! carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -- [ ] **Paso 5: Añadir `mod tui;` a main.rs** - -Encontrar este bloque en `crates/coven-cli/src/main.rs` (alrededor de las líneas 31–33 tras la inserción de `mod theme;` de la Fase 1): - -```rust -mod store; -mod theme; -mod verification; -``` - -Insertar `mod tui;` alfabéticamente entre `theme` y `verification`: - -```rust -mod store; -mod theme; -mod tui; -mod verification; -``` - -NO eliminar `mod chat;` todavía (la Tarea 3 se encarga de eso). Ambos módulos coexisten tras la Tarea 1. - -- [ ] **Paso 6: Verificar que el crate compila** - -```bash -cargo build -p coven-cli 2>&1 | tail -20 -``` - -Esperado: compila limpiamente. Algunas advertencias "unused import" sobre `crate::tui::chat` o sus submódulos son aceptables en la Tarea 1 — esas se consumirán en la Tarea 3. - -Si ves errores reales (no advertencias), PARAR y reportar BLOQUEADO con el texto del error. - -- [ ] **Paso 7: Ejecutar todos los tests** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Esperado: todos los tests existentes pasan. El módulo de chat (todavía en `src/chat.rs`) y sus tests están intactos. Conteo de tests: 172 unitarios + 4 smoke = 176 (igual que al final de la Fase 1). - -- [ ] **Paso 8: Commit** - -```bash -git add crates/coven-cli/src/tui/ crates/coven-cli/src/main.rs -git commit -m "refactor(tui): scaffold tui/chat module structure - -Empty submodule skeleton for the chat carve-out. Old chat.rs remains -the active implementation; this commit only adds the new file tree and -wires mod tui; into main.rs. Task 2 of the chat-module plan moves the -content; Task 3 deletes the old file. -" -``` - -- [ ] **Paso 9: Verificar que el commit aterrizó en la rama correcta** - -```bash -git log --oneline -2 -git rev-parse --abbrev-ref HEAD -``` - -Esperado: el nuevo commit está encima, y HEAD está en `feat/tui-chat-module`. Si no, PARAR y reportar. - ---- - -## Tarea 2: Mover todo el contenido de `chat.rs` a los nuevos archivos del módulo - -Esta es la mayor parte del trabajo. La estrategia: copiar cada sección del viejo `chat.rs` a su archivo nuevo de destino, arreglar imports + visibilidad, luego reemplazar `chat.rs` con un shim de reexportación (`pub use crate::tui::chat::*;`) para que el viejo callsite `chat::run_chat()` en `main.rs` siga funcionando durante la Tarea 2. La Tarea 3 elimina el shim y actualiza el callsite. - -**Archivos:** -- Modificar: `crates/coven-cli/src/tui/chat/mod.rs` (reemplazar stub con run_chat + reexportaciones) -- Modificar: `crates/coven-cli/src/tui/chat/app.rs` (reemplazar placeholder con código de estado) -- Modificar: `crates/coven-cli/src/tui/chat/render.rs` (reemplazar placeholder con renderizadores) -- Modificar: `crates/coven-cli/src/tui/chat/events.rs` (reemplazar placeholder con bucle de eventos) -- Modificar: `crates/coven-cli/src/chat.rs` (reducir a un shim de reexportación) - -- [ ] **Paso 1: cd al worktree y verificar la rama** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -git rev-parse --abbrev-ref HEAD -``` - -Esperado: `feat/tui-chat-module`. Si no, PARAR. - -- [ ] **Paso 2: Poblar `tui/chat/app.rs`** - -Abrir `crates/coven-cli/src/chat.rs` y copiar los siguientes rangos (los números de línea se refieren al chat.rs **actual** al momento del commit `9bcb69a`): - -- Líneas 33–85 (los tipos de datos: `MessageRole`, `ChatMessage`, `AgentInfo`, `InputMode`, `SlashCommandResult`, `App`) -- Línea 86 (la constante `SPINNER_FRAMES`) -- Líneas 88–457 (el bloque `impl App`) -- Líneas 459–471 (`fn discover_agents`) -- Líneas 990–992 (`fn timestamp_now`) -- Líneas 994–1002 (`fn truncate_str`) -- Líneas 1004–1111 (todo el bloque `#[cfg(test)] mod tests`) - -Reemplazar el placeholder en `crates/coven-cli/src/tui/chat/app.rs` con este contenido, en este orden: - -1. Comentario de documentación al inicio del archivo + sentencias use (reemplazar los imports de chat.rs por solo lo que app.rs necesita): - -```rust -//! Chat application state, behavior, and helpers. Owns `App` and all of its -//! methods; provides `discover_agents` and the spinner-frame data. - -use crate::harness; -``` - -2. Los tipos de datos de las líneas 33–69 de chat.rs. **Cambios de visibilidad (según la especificación):** - - `pub enum MessageRole` → mantener `pub` (reexportado vía mod.rs en el siguiente paso) - - `pub struct ChatMessage` → mantener `pub` - - `pub struct AgentInfo` → mantener `pub` - - `enum InputMode` → sin cambios (privado, permanece como `enum`) - - `enum SlashCommandResult` → sin cambios (privado) - -3. `struct App` (líneas 71–85): cambiar la visibilidad de privada a `pub(super)`: - -```rust -pub(super) struct App { - // ... unchanged fields ... -} -``` - -4. `const SPINNER_FRAMES: &[&str] = ...` (línea 86): cambiar a `pub(super)`: - -```rust -pub(super) const SPINNER_FRAMES: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧"]; -``` -(O copiar los glifos exactos de chat.rs:86 — los frames del spinner son los mismos caracteres del patrón Braille.) - -5. `impl App` (líneas 88–457): pegar sin cambios. - -6. `fn discover_agents` (líneas 459–471): cambiar a `pub(super)`: - -```rust -pub(super) fn discover_agents() -> Vec { - // ... unchanged body ... -} -``` - -7. `fn timestamp_now` (líneas 990–992): mantener privado: - -```rust -fn timestamp_now() -> String { - // ... unchanged body ... -} -``` - -8. `fn truncate_str` (líneas 994–1002): mantener privado: - -```rust -fn truncate_str(s: &str, max: usize) -> &str { - // ... unchanged body ... -} -``` - -9. El módulo de tests (líneas 1004–1111) — pegar con estos cambios quirúrgicos: - - **Eliminar** el test `chat_module_stays_single_file_to_avoid_rust_module_ambiguity` (líneas 1035–1059). - - **Eliminar** el import `use std::path::Path;` dentro de `mod tests` (solo ese test lo usaba; los demás no). - - Mantener los cuatro tests de comportamiento (`unknown_slash_command_returns_command_name_for_feedback`, `handle_input_clears_unknown_slash_command_and_reports_it`, `agent_command_without_argument_opens_picker_on_active_agent`, `unavailable_agent_selection_keeps_current_active_agent`) y ambos helpers (`app_with_agents`, `agent`) sin cambios. - -- [ ] **Paso 3: Poblar `tui/chat/render.rs`** - -Copiar los siguientes rangos desde `chat.rs` al nuevo `render.rs`: - -- Líneas 473–510 (`fn render_ui`) -- Líneas 512–538 (`fn render_status_bar`) -- Líneas 540–636 (`fn render_messages`) -- Líneas 638–672 (`fn render_input`) -- Líneas 674–700 (`fn render_hint_bar`) -- Líneas 702–779 (`fn render_help_overlay`) -- Líneas 781–838 (`fn render_agent_select`) - -Reemplazar el placeholder en `render.rs` con: - -1. Comentario de documentación al inicio del archivo + imports. Los renderizadores necesitan tipos de ratatui y el módulo theme: - -```rust -//! Chat TUI render functions. Pure view code; reads `App` state and emits -//! ratatui widgets. The entry point is `render_ui`; the other render_* fns -//! are private helpers it composes. - -use ratatui::{ - Frame, - layout::{Alignment, Constraint, Layout, Margin, Rect}, - style::{Color, Style}, - text::{Line, Span}, - widgets::{Block, Borders, Clear, List, ListItem, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, Wrap}, -}; - -use crate::theme::{self, AGENT_LABEL, DIM, HINT_KEY, PRIMARY, PRIMARY_STRONG, SURFACE, SURFACE_STRONG, USER_LABEL}; - -use super::app::{App, AgentInfo, InputMode, MessageRole, SPINNER_FRAMES}; -``` - -2. Cambiar `fn render_ui` a `pub(super) fn render_ui` (llamado por `events.rs` a continuación): - -```rust -pub(super) fn render_ui(f: &mut Frame, app: &mut App) { - // ... unchanged body ... -} -``` - -3. Todas las demás funciones `render_*` permanecen privadas (`fn`, no `pub`). Pegarlas sin cambios. - -- [ ] **Paso 4: Poblar `tui/chat/events.rs`** - -Copiar las líneas 863–988 desde `chat.rs` (la función `run_event_loop`) a `events.rs`. - -Reemplazar el placeholder con: - -```rust -//! Chat TUI event loop. Reads keyboard events via crossterm and dispatches -//! to `App` methods; calls `render_ui` between events. - -use std::io::Stdout; -use std::time::{Duration, Instant}; - -use anyhow::Result; -use crossterm::event::{self, Event, KeyCode, KeyModifiers}; -use ratatui::{Terminal, backend::CrosstermBackend}; - -use super::app::{App, SlashCommandResult}; -use super::render::render_ui; -``` - -Luego pegar `run_event_loop` con este cambio de firma: - -```rust -pub(super) fn run_event_loop( - terminal: &mut Terminal>, - app: &mut App, -) -> Result<()> { - // ... unchanged body ... -} -``` - -(La firma actual en chat.rs línea 863 empieza el cuerpo con los parámetros `terminal:` y `app:` — mantenerlos.) - -- [ ] **Paso 5: Poblar `tui/chat/mod.rs`** - -Reemplazar el stub creado en la Tarea 1 con el contenido real. El mod.rs contiene `run_chat` y las reexportaciones públicas. - -```rust -//! Ratatui-based chat TUI. State lives in `app`, view in `render`, event loop -//! in `events`. The entry point `run_chat` manages the raw-terminal lifecycle. - -mod app; -mod events; -mod render; - -// Re-export the public types so callers see them at `tui::chat::*` instead of -// having to reach into `tui::chat::app::*`. Matches the surface of the old -// `chat::*` module from before the carve-out. -pub use app::{AgentInfo, ChatMessage, MessageRole}; - -use std::io::stdout; - -use anyhow::Result; -use crossterm::{ - event::{DisableMouseCapture, EnableMouseCapture}, - execute, - terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, -}; -use ratatui::{backend::CrosstermBackend, Terminal}; - -use app::App; -use events::run_event_loop; -``` - -Luego pegar el cuerpo de `pub fn run_chat()` desde chat.rs líneas 840–861 sin cambios. El cuerpo llama a `App::new()` y `run_event_loop(...)` — ambos están importados en el bloque `use` de arriba, por lo que no se necesitan ediciones del cuerpo. - -Eliminar el `#![allow(dead_code)]` de la parte superior de mod.rs que se añadió en la Tarea 1. - -- [ ] **Paso 6: Reemplazar `chat.rs` con un shim de reexportación** - -Reemplazar todo el contenido de `crates/coven-cli/src/chat.rs` (1111 líneas) por estas 3 líneas: - -```rust -//! Temporary re-export shim during the Phase 2 carve-out. Removed in Task 3 -//! of the chat-module plan; do not add new content here. - -pub use crate::tui::chat::*; -``` - -Esto mantiene funcionando el callsite `chat::run_chat()` de `main.rs` (ahora resuelve a `tui::chat::run_chat` a través de la reexportación con glob). El shim se elimina en la Tarea 3. - -- [ ] **Paso 7: Verificar que el crate compila** - -```bash -cargo build -p coven-cli 2>&1 | tail -30 -``` - -Esperado: compila limpiamente sin errores. Pueden quedar algunas advertencias (p. ej., "unused import" si un `use` ahora es redundante). Si ves errores, la causa más probable es: - -- Un elemento `pub(super)` que necesita `pub` para la reexportación del shim. El shim de chat.rs `pub use crate::tui::chat::*;` reexporta solo elementos `pub`, no `pub(super)`. Los elementos `run_chat`, `MessageRole`, `ChatMessage`, `AgentInfo` deben ser `pub` en `tui::chat::*` para que el shim los encuentre. -- Un import faltante en uno de los archivos nuevos. Contrastar la sección de imports en cada archivo con lo que lista la especificación. - -- [ ] **Paso 8: Ejecutar todos los tests** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Esperado: **175 tests unitarios** + 4 smoke tests pasan (un test unitario menos que al inicio de la Tarea 2 — la salvaguarda eliminada). - -Si un test falla, la causa más probable es que el archivo de tests ya no compila (el acceso privado a campos de `App` antes era legal pero ahora requiere que el test esté en el mismo archivo que `App` — lo está, en `app.rs`, así que esto debería funcionar). - -- [ ] **Paso 9: Commit** - -```bash -git add crates/coven-cli/src/tui/ crates/coven-cli/src/chat.rs -git commit -m "refactor(tui): move chat.rs content into tui/chat/* submodule - -Pure code motion. chat.rs becomes a re-export shim that points at -crate::tui::chat::* so main.rs's existing chat::run_chat() call keeps -working. The shim and the old mod chat; declaration get deleted in -Task 3 along with the guardrail test (which fails as soon as chat.rs -is removed). -" -``` - -- [ ] **Paso 10: Verificar el commit en la rama correcta** - -```bash -git log --oneline -3 -git rev-parse --abbrev-ref HEAD -``` - -Esperado: nuevo commit encima, HEAD = `feat/tui-chat-module`. - ---- - -## Tarea 3: Eliminar `chat.rs` y actualizar `main.rs` - -Tras la Tarea 2, `chat.rs` es solo un shim de reexportación. Esta tarea lo elimina, quita `mod chat;` de main.rs, actualiza el callsite a `tui::chat::run_chat()` y verifica los criterios de aceptación finales. - -**Archivos:** -- Eliminar: `crates/coven-cli/src/chat.rs` -- Modificar: `crates/coven-cli/src/main.rs` (eliminar `mod chat;`, actualizar línea 150) - -- [ ] **Paso 1: cd al worktree, verificar rama** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -git rev-parse --abbrev-ref HEAD -``` - -Esperado: `feat/tui-chat-module`. - -- [ ] **Paso 2: Eliminar `crates/coven-cli/src/chat.rs`** - -```bash -rm crates/coven-cli/src/chat.rs -git status --short -``` - -Esperado: muestra `D crates/coven-cli/src/chat.rs`. - -- [ ] **Paso 3: Actualizar `main.rs` — eliminar `mod chat;`** - -En `crates/coven-cli/src/main.rs`, encontrar el bloque de declaraciones `mod` (alrededor de las líneas 21–35). Eliminar la línea `mod chat;`. El bloque mod restante debería verse así: - -```rust -mod api; -mod control_plane; -mod daemon; -mod harness; -mod openclaw_repo; -mod patch; -mod pc; -mod project; -mod pty_runner; -mod store; -mod theme; -mod tui; -mod verification; -``` - -(Nota: `mod chat;` estaba originalmente entre `mod api;` y `mod control_plane;`.) - -- [ ] **Paso 4: Actualizar `main.rs` — cambiar el callsite del chat** - -En `main.rs` encontrar la línea 150 (aproximada — la línea exacta se desplaza cuando se elimina `mod chat;`): - -```rust -Some(Command::Chat) => chat::run_chat(), -``` - -Reemplazar con: - -```rust -Some(Command::Chat) => tui::chat::run_chat(), -``` - -Este es el **único** callsite en main.rs que usa el módulo de chat. Grep para confirmar: - -```bash -grep -nE '\bchat::' crates/coven-cli/src/main.rs -``` - -Salida esperada: una línea, el nuevo `tui::chat::run_chat()`. Si ves coincidencias adicionales, también necesitan ser reemplazadas. - -- [ ] **Paso 5: Verificar que el crate compila** - -```bash -cargo build -p coven-cli 2>&1 | tail -20 -``` - -Esperado: compila limpiamente con cero advertencias. - -Si ves: -- "unresolved module `chat`" — te saltaste el Paso 3 (la eliminación de `mod chat;`) o el Paso 4 (la actualización del callsite). Volver a hacer grep. -- "file not found: chat.rs" — la build todavía está buscando chat.rs. Confirmar que `mod chat;` ya no está en main.rs. -- "function `run_chat` is private" — `run_chat` en `tui/chat/mod.rs` no es `pub`. Revisar el contenido de `mod.rs` de la Tarea 2; se requiere la firma `pub fn run_chat`. - -- [ ] **Paso 6: Ejecutar todos los tests** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Esperado: **175 tests unitarios + 4 smoke tests pasan** (igual que el conteo de la Tarea 2). - -- [ ] **Paso 7: Ejecutar clippy** - -```bash -cargo clippy -p coven-cli --no-deps 2>&1 | tail -10 -``` - -Esperado: cero advertencias (sin regresión del estado limpio de la Fase 1). - -- [ ] **Paso 8: Verificar los criterios de aceptación mediante comprobaciones del sistema de archivos** - -```bash -# Criterion 1: chat.rs is gone -test -e crates/coven-cli/src/chat.rs && echo "FAIL: chat.rs still exists" || echo "ok: chat.rs deleted" - -# Criterion 2: tui/mod.rs exists with the expected content -cat crates/coven-cli/src/tui/mod.rs - -# Criterion 3: tui/chat/ has exactly 4 .rs files -ls crates/coven-cli/src/tui/chat/ - -# Criterion 4: main.rs uses tui::chat::run_chat -grep -nE 'tui::chat::run_chat|chat::run_chat' crates/coven-cli/src/main.rs -``` - -Esperado: -- `ok: chat.rs deleted` -- `tui/mod.rs` muestra el comentario de documentación + `pub mod chat;` -- `ls` muestra exactamente `mod.rs app.rs render.rs events.rs` (4 archivos, sin extras) -- El último grep muestra una línea, con `tui::chat::run_chat()` - -- [ ] **Paso 9: Verificar que el test de salvaguarda eliminado se haya ido** - -```bash -grep -rn 'chat_module_stays_single_file' crates/coven-cli/src/ 2>&1 || echo "ok: guardrail test deleted" -``` - -Esperado: `ok: guardrail test deleted`. Si algo coincide, la salvaguarda todavía existe en algún lugar (debería haber sido eliminada al copiar los tests a `app.rs` en el Paso 2 de la Tarea 2). Eliminarla ahora y volver a ejecutar. - -- [ ] **Paso 10: Commit** - -```bash -git add crates/coven-cli/src/main.rs crates/coven-cli/src/chat.rs -git commit -m "refactor(tui): delete chat.rs shim and finalize chat carve-out - -Removes the re-export shim from Task 2, drops mod chat; from main.rs, -and points the Chat command at tui::chat::run_chat() directly. The -guardrail test (which previously prevented this split) was removed in -Task 2 when its containing module file was rewritten. - -Acceptance criteria from the design spec all met: -- src/chat.rs deleted -- src/tui/chat/ has exactly mod.rs, app.rs, render.rs, events.rs -- 175 unit + 4 smoke tests pass -- cargo clippy clean -" -``` - -- [ ] **Paso 11: Verificar el estado final** - -```bash -git log --oneline -4 -git rev-parse --abbrev-ref HEAD -git status --short -``` - -Esperado: 3 commits nuevos encima del tip de la Fase 1 (`9bcb69a`): -``` - refactor(tui): delete chat.rs shim and finalize chat carve-out - refactor(tui): move chat.rs content into tui/chat/* submodule - refactor(tui): scaffold tui/chat module structure -9bcb69a chore(theme): silence dead-code warnings for future-use tokens -``` - -La rama es `feat/tui-chat-module`. El status está limpio (sin cambios sin commitear). - ---- - -## Hecho - -Cuando se complete la Tarea 3, cada criterio de aceptación de la especificación se cumple: - -1. ✅ `src/chat.rs` ya no existe — Tarea 3 Paso 2. -2. ✅ `src/tui/mod.rs` existe con `pub mod chat;` — Tarea 1 Paso 2. -3. ✅ `src/tui/chat/` contiene exactamente `mod.rs`, `app.rs`, `render.rs`, `events.rs` — Tareas 1–2. -4. ✅ `src/main.rs` tiene `mod tui;` y `tui::chat::run_chat()` — Tareas 1 + 3. -5. ✅ `cargo build -p coven-cli` tiene éxito limpiamente — Tarea 3 Paso 5. -6. ✅ `cargo test -p coven-cli` pasa; el conteo unitario baja exactamente en uno — Tarea 3 Paso 6. -7. ✅ `cargo clippy -p coven-cli --no-deps` produce cero advertencias — Tarea 3 Paso 7. -8. ✅ Ningún elemento expuesto de forma nueva más allá de la superficie de hoy — Reglas de visibilidad de las Tareas 2–3. -9. ⏳ Manual: lanzar `coven chat` muestra la misma TUI que antes. No automatizable; verificar a ojo si es conveniente. - -Tras la Tarea 3, hacer push a origin y abrir un PR apilado sobre #56. diff --git a/docs/es/superpowers/specs/2026-05-15-tui-chat-module-design.md b/docs/es/superpowers/specs/2026-05-15-tui-chat-module-design.md deleted file mode 100644 index c64807d9..00000000 --- a/docs/es/superpowers/specs/2026-05-15-tui-chat-module-design.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: "Diseño: extracción del módulo de chat TUI en coven-cli" -description: "Especificación en español de la fase 2 de la limpieza del TUI: descompone chat.rs en estado, vista, controlador y ciclo de vida mediante motion puro del código." ---- - -# Extracción del módulo de chat TUI — Diseño - -**Estado:** Aprobado — listo para el plan de implementación -**Fecha:** 2026-05-15 -**Alcance:** Fase 2 del esfuerzo de limpieza estructural de la TUI. Apilado sobre la Fase 1 ([`feat/tui-theme-module`](https://github.com/OpenCoven/coven/pull/56)); no puede fusionarse hasta que esa aterrice. -**Enfoque:** Movimiento puro de código. Sin renombrados, sin cambios de firma, sin cambios de comportamiento. - ---- - -## Problema - -`crates/coven-cli/src/chat.rs` tiene 1111 líneas tras la migración de temas de la Fase 1. Es un único archivo que contiene los tipos de datos de la TUI de chat basada en ratatui, el estado de la aplicación, ~370 líneas de código de renderizado repartidas en 7 funciones de render, el bucle de eventos, el punto de entrada público y los tests. Las responsabilidades del archivo — modelo de estado, vista, controlador y ciclo de vida — están todas mezcladas. - -Síntomas que motivan la división: - -- El archivo es difícil de manejar para navegar y revisar. El código de render (líneas 473–838) es un único bloque contiguo. -- `impl App` (líneas 88–457) tiene 369 líneas por sí solo. -- Un test de regresión existente (`chat_module_stays_single_file_to_avoid_rust_module_ambiguity`, añadido en `fa786f1`) impide activamente la división — su eliminación es el disparador de este trabajo. - -El nuevo módulo `crate::theme` que aterrizó en la Fase 1 ya demuestra el patrón que queremos para las superficies de TUI: una responsabilidad lógica por archivo, los puntos de llamada importan vía `use`. - -## No-objetivos - -Explícitamente fuera del alcance de la Fase 2 y no deben colarse: - -- **Cambios de comportamiento** de cualquier tipo. Los renderizadores producen la misma salida. El bucle de eventos procesa las mismas teclas. La CLI se comporta de manera idéntica. -- **Ajuste de API.** `pub enum MessageRole`, `pub struct ChatMessage`, `pub struct AgentInfo` permanecen `pub` aunque ningún llamador fuera del módulo de chat los importe hoy. Ajustarlos a `pub(super)` es una preocupación aparte (candidato para un PR de seguimiento; ver Fase 2.1). -- **Extracción de helpers.** `render_messages` (el renderizador más grande con ~98 líneas) no se refactoriza. Las funciones helper internas no se extraen. -- **División de `main.rs`.** Fase 3 — fuera de alcance. -- **Extracción del launcher / explorador de sesiones.** Fase 4 — fuera de alcance. (Sí creamos el módulo padre `tui/` en previsión, pero solo `tui::chat` vive bajo él por ahora.) -- **Nuevos tests.** La Fase 2 hereda los tests existentes y elimina la salvaguarda. No se añaden nuevos tests de comportamiento. - -## Restricciones - -- **Ningún elemento del módulo de chat se expone de forma nueva más allá de `tui::chat::run_chat`.** La visibilidad se preserva exactamente como hoy (movimiento puro de código). -- **El crate sigue siendo un único binario.** Sin nuevos miembros del workspace, sin exposición de biblioteca. -- **`cargo clippy -p coven-cli --no-deps` produce cero advertencias**, preservando el estado limpio posterior a la Fase 1. - -## Estructura del módulo - -``` -crates/coven-cli/src/ -├── tui/ -│ ├── mod.rs (~10 líneas: `pub mod chat;`) -│ └── chat/ -│ ├── mod.rs (~40 líneas: pub fn run_chat + ciclo de vida de terminal en bruto) -│ ├── app.rs (~530 líneas: estado, comportamiento, helpers, tests) -│ ├── render.rs (~380 líneas: 7 funciones de render) -│ └── events.rs (~150 líneas: bucle de eventos) -├── main.rs (una edición: `mod chat;` → `mod tui;` y `chat::run_chat()` → `tui::chat::run_chat()`) -└── ... (otros archivos sin cambios) -``` - -`crates/coven-cli/src/chat.rs` se elimina por completo. El compilador de Rust impone la no coexistencia de `src/chat.rs` y `src/chat/mod.rs`, por lo que la eliminación de la forma de archivo único es obligatoria una vez que aterriza la forma de directorio. (Estamos usando la forma `src/tui/chat/`, no `src/chat/`, pero el principio es el mismo: no puede quedar ningún `src/chat.rs`.) - -## Mapeo de contenido por archivo - -### `tui/mod.rs` (nuevo) - -```rust -//! TUI surfaces for the coven CLI. Currently hosts the chat module; Phases 3–4 -//! will land the launcher and session-browser carve-outs from main.rs here. - -pub mod chat; -``` - -### `tui/chat/mod.rs` - -Contiene el punto de entrada público y el ciclo de vida de terminal en bruto (habilitar modo raw, entrar en pantalla alternativa, construir App, ejecutar bucle, restaurar terminal al drop). - -| Desde `chat.rs` | Nueva ubicación | -|---|---| -| Líneas 840–861 (`pub fn run_chat`) | `tui/chat/mod.rs` | -| (declaraciones de módulo) | `mod app; mod events; mod render;` | - -Imports necesarios: -```rust -use std::io::stdout; -use anyhow::Result; -use crossterm::{ - execute, - event::{DisableMouseCapture, EnableMouseCapture}, - terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, -}; -use ratatui::{Terminal, backend::CrosstermBackend}; -``` - -### `tui/chat/app.rs` - -Estado, comportamiento, helpers del ciclo de vida y tests. La mitad de "datos + métodos" del módulo. - -| Desde `chat.rs` | Nueva ubicación | Visibilidad | -|---|---|---| -| Líneas 33–38 (MessageRole) | `app.rs` | `pub` (preservada de hoy) | -| Líneas 40–46 (ChatMessage) | `app.rs` | `pub` (preservada) | -| Líneas 48–54 (AgentInfo) | `app.rs` | `pub` (preservada) | -| Líneas 56–60 (InputMode) | `app.rs` | `enum` privado (preservado) | -| Líneas 62–69 (SlashCommandResult) | `app.rs` | `enum` privado (preservado) | -| Líneas 71–85 (struct App) | `app.rs` | `pub(super)` — era privado al módulo en chat.rs; ahora debe cruzar la nueva frontera de archivo hacia `render.rs` y `events.rs` | -| Línea 86 (SPINNER_FRAMES) | `app.rs` | `pub(super)` (usado tanto por `App::tick` como por `render_status_bar`) | -| Líneas 88–457 (impl App) | `app.rs` | sin cambios | -| Líneas 459–471 (discover_agents) | `app.rs` | `pub(super)` (llamado por `run_chat` en `mod.rs`) | -| Líneas 990–992 (timestamp_now) | `app.rs` | `pub(super)` es innecesario — los únicos llamadores están en el propio `app.rs`. Mantener privado. | -| Líneas 994–1002 (truncate_str) | `app.rs` | igual — solo lo llama `App::simulate_agent_response`. Mantener privado. | -| Líneas 1004–1111 (mod tests) | `app.rs` (tras descartar la salvaguarda) | `#[cfg(test)] mod tests` | - -**Nota sobre visibilidad.** El movimiento puro de código preserva el comportamiento observable. Pero los elementos `App`, `SPINNER_FRAMES`, `discover_agents`, `render_ui`, `run_event_loop`, y los tipos `MessageRole`/`ChatMessage`/`AgentInfo` que antes eran privados al módulo (o solo crate-pub pero sin uso) deben ahora tener una visibilidad apropiada para cruzar la nueva frontera de submódulo. La nueva visibilidad es la más restrictiva que aún funciona: - -- Elementos consumidos solo dentro de `app.rs`: permanecen privados (timestamp_now, truncate_str, InputMode, SlashCommandResult). -- Elementos consumidos a través de `app.rs`/`render.rs`/`events.rs`: `pub(super)` (App, SPINNER_FRAMES, MessageRole, AgentInfo, discover_agents). -- Elementos consumidos por `mod.rs`: `pub(super)` (run_event_loop en events.rs, render_ui en render.rs, App + discover_agents). -- Los tipos previamente `pub` `MessageRole`, `ChatMessage`, `AgentInfo`: este es el único juicio. Hoy son `pub` a nivel de crate (visibles como `chat::MessageRole` etc.). El objetivo del Enfoque A de "preservar la visibilidad" dice que deben permanecer visibles a nivel de crate tras el movimiento. **Decisión:** declararlos `pub` dentro de `app.rs`, y reexportarlos vía `pub use app::{MessageRole, ChatMessage, AgentInfo};` en `tui/chat/mod.rs`. La ruta visible al crate se mantiene corta (`tui::chat::ChatMessage` en lugar de `tui::chat::app::ChatMessage`), coincidiendo con la superficie de hoy módulo el prefijo `tui::`. - -### `tui/chat/render.rs` - -Las 7 funciones de render y el consumidor de SPINNER_FRAMES. Código de vista puro. - -| Desde `chat.rs` | Nueva ubicación | Visibilidad | -|---|---|---| -| Líneas 473–510 (render_ui) | `render.rs` | `pub(super)` (llamado por `events.rs` vía `run_event_loop`) | -| Líneas 512–538 (render_status_bar) | `render.rs` | `fn` privada (preservada) | -| Líneas 540–636 (render_messages) | `render.rs` | `fn` privada | -| Líneas 638–672 (render_input) | `render.rs` | `fn` privada | -| Líneas 674–700 (render_hint_bar) | `render.rs` | `fn` privada | -| Líneas 702–779 (render_help_overlay) | `render.rs` | `fn` privada | -| Líneas 781–838 (render_agent_select) | `render.rs` | `fn` privada | - -Imports necesarios: -```rust -use ratatui::{ - Frame, - layout::{Alignment, Constraint, Layout, Margin, Rect}, - style::{Color, Style}, - text::{Line, Span}, - widgets::{Block, Borders, Clear, List, ListItem, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, Wrap}, -}; -use crate::theme::{self, AGENT_LABEL, DIM, HINT_KEY, PRIMARY, PRIMARY_STRONG, SURFACE, SURFACE_STRONG, USER_LABEL}; -use super::app::{App, AgentInfo, InputMode, MessageRole, SPINNER_FRAMES}; -``` - -### `tui/chat/events.rs` - -El bucle de eventos. - -| Desde `chat.rs` | Nueva ubicación | Visibilidad | -|---|---|---| -| Líneas 863–988 (run_event_loop) | `events.rs` | `pub(super)` (llamado desde `run_chat` en `mod.rs`) | - -Imports necesarios: -```rust -use std::io::Stdout; -use std::time::{Duration, Instant}; -use anyhow::Result; -use crossterm::event::{self, Event, KeyCode, KeyModifiers}; -use ratatui::{Terminal, backend::CrosstermBackend}; -use super::app::{App, SlashCommandResult}; -use super::render::render_ui; -``` - -## Vista de la API pública desde fuera del módulo de chat - -Tras la división, el único elemento visible a nivel de crate es `tui::chat::run_chat` (y los tipos reexportados `MessageRole`, `ChatMessage`, `AgentInfo`, que permanecen `pub` según el objetivo de preservación de visibilidad del Enfoque A). `main.rs` referencia exactamente uno de ellos: - -```rust -// crates/coven-cli/src/main.rs línea 150 (antes): -Some(Command::Chat) => chat::run_chat(), - -// después: -Some(Command::Chat) => tui::chat::run_chat(), -``` - -Y la declaración `mod` en la línea 23 (post–Fase 1): - -```rust -// antes: -mod chat; - -// después: -mod tui; -``` - -La posición alfabética de la declaración `mod` se desplaza desde `mod chat;` (entre `mod api;` y `mod control_plane;`) a `mod tui;` (entre `mod theme;` y `mod verification;`). - -## Tests - -### Migración - -Los cinco tests/helpers existentes (`app_with_agents`, `agent`, más 4 tests de comportamiento que apuntan a métodos de `App`) se mueven intactos al bloque `#[cfg(test)] mod tests` de `app.rs`. - -El test de salvaguarda `chat_module_stays_single_file_to_avoid_rust_module_ambiguity` (chat.rs:1036) **se elimina**. Su propósito era prevenir exactamente la división que implementa esta especificación. El `use std::path::Path;` que requería se elimina junto con él. - -### Sin salvaguarda de reemplazo - -El propio compilador de Rust rechaza el único caso verdaderamente ambiguo (que coexistan `src/tui/chat.rs` y `src/tui/chat/mod.rs` al mismo tiempo). Un test que afirme "estos archivos específicos existen con esta disposición" sería una restricción mantenida a través de cada reestructuración futura sin beneficio funcional. - -## Criterios de aceptación - -La Fase 2 está completa cuando: - -1. `crates/coven-cli/src/chat.rs` ya no existe (`git ls-files` no devuelve nada para él; el árbol de trabajo no tiene tal archivo). -2. `crates/coven-cli/src/tui/mod.rs` existe con el contenido único `pub mod chat;` (más el comentario de documentación a nivel de módulo). -3. `crates/coven-cli/src/tui/chat/` contiene exactamente cuatro archivos: `mod.rs`, `app.rs`, `render.rs`, `events.rs`. Ningún otro. -4. `crates/coven-cli/src/main.rs` tiene `mod tui;` (posición alfabética ajustada) y `tui::chat::run_chat()` en la línea 150. -5. `cargo build -p coven-cli` tiene éxito con cero advertencias. -6. `cargo test -p coven-cli` pasa; el conteo de tests unitarios baja exactamente en uno (el test de salvaguarda eliminado). Los smoke tests pasan en 4. -7. `cargo clippy -p coven-cli --no-deps` produce cero advertencias. -8. Ningún elemento del módulo de chat se expone de forma nueva más allá de `tui::chat::run_chat`, `tui::chat::ChatMessage`, `tui::chat::AgentInfo`, `tui::chat::MessageRole` (los tres tipos reexportados de la superficie de hoy). -9. Smoke check manual: lanzar `coven chat` abre la TUI y renderiza sin regresiones visibles (mismos colores, mismo layout, mismas combinaciones de teclas). - -## Escala de diff estimada - -| Archivo | Acción | Líneas | -|---|---|---| -| `crates/coven-cli/src/chat.rs` | Eliminar | -1111 | -| `crates/coven-cli/src/tui/mod.rs` | Crear | ~10 | -| `crates/coven-cli/src/tui/chat/mod.rs` | Crear | ~40 | -| `crates/coven-cli/src/tui/chat/app.rs` | Crear | ~530 | -| `crates/coven-cli/src/tui/chat/render.rs` | Crear | ~380 | -| `crates/coven-cli/src/tui/chat/events.rs` | Crear | ~150 | -| `crates/coven-cli/src/main.rs` | Edición de 1 línea + 1 intercambio de mod | ±2 | - -Neto: ~0 líneas (el archivo se reorganiza, no se reduce). El test de salvaguarda eliminado quita ~25 líneas del total final. diff --git a/docs/ru/API-CONTRACT.md b/docs/ru/API-CONTRACT.md deleted file mode 100644 index 33f9ea1b..00000000 --- a/docs/ru/API-CONTRACT.md +++ /dev/null @@ -1,337 +0,0 @@ ---- -title: "Контракт локального API Coven (coven.daemon.v1)" -description: "Версионированный контракт coven.daemon.v1 под /api/v1: согласование health, обнаружение capabilities, конверты ошибок и правила аддитивной совместимости." ---- - -# Контракт локального API Coven - -Socket API демона Coven — это публичная граница совместимости для comux и внешних клиентов, таких как external OpenClaw bridge plugin. - -## Текущая стабильная версия - -- `GET /api/v1/health` предоставляет `apiVersion: "coven.daemon.v1"`, `covenVersion` и читаемый машиной объект `capabilities`. -- Клиенты должны читать `/api/v1/health` перед предположением о любой форме ответа от других endpoint'ов. -- Старые неверсионированные маршруты, такие как `GET /health`, остаются алиасами раннего MVP; новые клиенты должны использовать `/api/v1`. -- Клиенты плоскости управления должны обнаруживать capabilities до отправки id действий. -- Все сбои API возвращаются как структурированные конверты `{ "error": { "code", "message", "details" } }`. -- События включают монотонный курсор `seq` для инкрементных чтений. - -## `GET /api/v1/health` - -`GET /api/v1/health` возвращает доступность демона, именованную версию контракта, версию coven и читаемые машиной capabilities: - -```json -{ - "ok": true, - "apiVersion": "coven.daemon.v1", - "covenVersion": "0.0.0", - "capabilities": { - "sessions": true, - "events": true, - "eventCursor": "sequence", - "structuredErrors": true - }, - "daemon": { - "pid": 12345, - "startedAt": "2026-05-09T06:43:00Z", - "socket": "/Users/alice/.coven/coven.sock" - } -} -``` - -Если метаданные демона недоступны, `daemon` может быть `null`. - -### Поля capability - -| Поле | Тип | Описание | -|-------------------|---------|-------------------------------------------------------------------| -| `sessions` | boolean | API сессий (`/sessions`, `/sessions/:id`) доступен. | -| `events` | boolean | API событий (`/events`) доступен. | -| `eventCursor` | string | Поддерживаемый тип курсора; `"sequence"` означает, что `afterSeq` стабилен. | -| `structuredErrors`| boolean | Все ошибки используют форму `{ error: { code, message, details } }`. | - -## Структурированный конверт ошибки - -```mermaid -flowchart TD - Req[Incoming request] --> Parse{Parse + version check} - Parse -- bad shape --> ErrInvalid["400 invalid_request"] - Parse -- unknown version --> ErrInvalid - Parse -- ok --> Route{Route exists?} - Route -- no --> ErrNotFound["404 not_found"] - Route -- yes --> Validate{Field validation} - Validate -- cwd outside root --> ErrInvalid - Validate -- unknown harness/action --> ErrInvalid - Validate -- ok --> Action{Resource lookup} - Action -- session missing --> ErrSession["404 session_not_found"] - Action -- session not live --> ErrLive["409 session_not_live"] - Action -- launch (PTY/pipe spawn, init write, harness startup) fails --> ErrLaunch["500 launch_failed"] - Action -- send_input fails --> ErrSend["500 send_input_failed"] - Action -- kill_session fails --> ErrKill["500 kill_failed"] - Action -- runtime down --> ErrRuntime["503 runtime_unavailable"] - Action -- internal panic --> ErrInternal["500 internal_error"] - Action -- ok --> Success[Documented success shape] - - ErrInvalid & ErrNotFound & ErrSession & ErrLive & ErrLaunch & ErrSend & ErrKill & ErrRuntime & ErrInternal -->|"{ error: { code, message, details } }"| Client[Client branches on code] -``` - -Все ошибки API используют следующий стабильный конверт. Клиенты должны ветвиться по `error.code`, а не по `error.message`: - -```json -{ - "error": { - "code": "session_not_found", - "message": "Session was not found.", - "details": { - "sessionId": "abc-123" - } - } -} -``` - -`details` опционален и включается, когда полезен дополнительный контекст. - -### Стабильные коды ошибок - -| Код | HTTP-статус | Описание | -|------------------------|-------------|--------------------------------------------------| -| `not_found` | 404 | Общий маршрут не найден. | -| `invalid_request` | 400 или 404 | Некорректный запрос, неизвестный id harness, отсутствует обязательное поле, или неподдерживаемая версия API. | -| `session_not_found` | 404 | Id сессии не существует. | -| `session_not_live` | 409 | Сессия существует, но не выполняется. | -| `project_root_violation`| 400 | Зарезервировано. Нарушения cwd сейчас возвращают `invalid_request`; продвижение в отдельный код позволит клиентам ветвиться без парсинга текста. | -| `pty_spawn_failed` | 500 | Зарезервировано. Сбои spawn PTY сейчас возвращают `launch_failed`; продвижение в отдельный код позволит различать "не удалось открыть PTY" и "CLI harness упал при старте". | -| `launch_failed` | 500 | Демон принял payload запуска, но runtime (PTY/pipe spawn, начальная запись, старт CLI harness) дал сбой. `details.sessionId` — строка, помеченная как `failed`. | -| `send_input_failed` | 500 | Демон принял payload ввода, но запись в runtime дала сбой (закрытый pipe, мёртвый процесс, ошибка IO). `details.sessionId` — затронутая сессия. | -| `kill_failed` | 500 | Демон принял запрос kill, но сигнал/вызов runtime дал сбой (нет прав, отсутствует процесс, ошибка IO). `details.sessionId` — затронутая сессия. | -| `runtime_unavailable` | 503 | Runtime сессии недоступен. | -| `internal_error` | 500 | Неожиданная внутренняя ошибка. | - -## Форма каталога capabilities (`v1`) - -`GET /api/v1/capabilities` возвращает каталог capabilities демона/плоскости управления. Это предполагаемый handshake клиента чата/ввода для решения, какие действия показывать или маршрутизировать через Coven. - -```json -{ - "capabilities": [ - { - "id": "coven.control.actions", - "label": "Coven control-plane action router", - "adapter": "coven-daemon", - "status": "available", - "policy": "allow", - "actions": ["coven.capabilities.refresh"] - }, - { - "id": "desktop.automation", - "label": "Desktop automation adapters", - "adapter": "desktop-use", - "status": "planned", - "policy": "requiresApproval", - "actions": [] - } - ] -} -``` - -Известные значения enum в `v1`: - -- `status`: `available`, `planned` -- `policy`: `allow`, `requiresApproval` - -Клиенты должны игнорировать неизвестные будущие id capabilities и id действий, если они не поддерживают их явно. - -## Форма действия управления (`v1`) - -`POST /api/v1/actions` принимает конверт действия в форме политики. Демон валидирует id действия до того, как разрешена любая работа адаптера. - -```json -{ - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "args": {} -} -``` - -Безопасные действия, завершённые немедленно, возвращают `200`: - -```json -{ - "ok": true, - "accepted": true, - "action": "coven.capabilities.refresh", - "status": "completed", - "event": { - "kind": "capabilities.refreshed", - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "payload": { "capabilities": 3 } - } -} -``` - -Неизвестные id действий возвращают `400` и отказываются в закрытом виде: - -```json -{ - "ok": false, - "accepted": false, - "action": "desktop.deleteEverything", - "status": "rejected", - "reason": "unknown action `desktop.deleteEverything`" -} -``` - -## Форма записи сессии (`v1`) - -В `v1` ответы сессий остаются как сырые объекты JSON, используя snake_case имена полей демона на Rust. - -Endpoint'ы, возвращающие эту форму: - -- `GET /api/v1/sessions` → `SessionRecord[]` -- `POST /api/v1/sessions` → `SessionRecord` -- `GET /api/v1/sessions/:id` → `SessionRecord` - -```json -{ - "id": "session-1", - "project_root": "/repo", - "harness": "codex", - "title": "Fix the tests", - "status": "running", - "exit_code": null, - "archived_at": null, - "created_at": "2026-05-09T06:43:00Z", - "updated_at": "2026-05-09T06:43:05Z" -} -``` - -## Форма записи события и курсорная пагинация (`v1`) - -`GET /api/v1/events` возвращает пагинированный конверт с монотонными курсорами `seq`. - -### Параметры query - -| Параметр | Обязателен | Описание | -|---------------|------------|---------------------------------------------------------| -| `sessionId` | Да | Сессия, для которой нужно получить события. | -| `afterSeq` | Нет | Возвращает только события с `seq > afterSeq` (предпочтительно). | -| `afterEventId`| Нет | Курсор совместимости — разрешается в позицию последовательности. | -| `limit` | Нет | Максимальное число возвращаемых событий (применяется демоном, макс 1000). | - -### Конверт ответа - -```json -{ - "events": [ - { - "seq": 42, - "id": "event-uuid", - "session_id": "session-uuid", - "kind": "output", - "payload_json": "{\"data\":\"hello\"}", - "created_at": "2026-05-09T06:43:10Z" - } - ], - "nextCursor": { - "afterSeq": 42 - }, - "hasMore": false -} -``` - -`nextCursor` равен `null`, когда нет событий. `hasMore` равен `true`, когда применён `limit` и могут существовать больше событий. - -### Шаблон инкрементного чтения - -1. Опрашивай `GET /events?sessionId=`, чтобы получить все события (с опциональным `limit`). -2. Используй `nextCursor.afterSeq` в последующих запросах: `GET /events?sessionId=&afterSeq=`. -3. Повторяй, пока `hasMore` не станет `false`. - -Это даёт клиентам стабильные инкрементные чтения. Доставка exactly-once также требует чекпоинтинга на стороне клиента и идемпотентности. - -```mermaid -sequenceDiagram - participant Client - participant Daemon as /api/v1/events - - Client->>Daemon: GET ?sessionId=S1 - Daemon-->>Client: { events: [seq 1..50], nextCursor: { afterSeq: 50 }, hasMore: true } - Client->>Client: persist last seq = 50 - Client->>Daemon: GET ?sessionId=S1&afterSeq=50 - Daemon-->>Client: { events: [seq 51..78], nextCursor: { afterSeq: 78 }, hasMore: false } - Client->>Client: persist last seq = 78 - - note over Client,Daemon: Client crash + restart - Client->>Daemon: GET ?sessionId=S1&afterSeq=78 - Daemon-->>Client: { events: [seq 79..82], nextCursor: { afterSeq: 82 }, hasMore: false } -``` - -Сохранение `afterSeq` переживает перезапуски демона: события append-only, а номера seq монотонные, поэтому возобновлённый опрос всегда подбирает там, где остановился. - -## Формы ответа живого управления (`v1`) - -Оба endpoint'а живого управления возвращают одну и ту же форму принятого ответа при успехе: - -- `POST /api/v1/sessions/:id/input` -- `POST /api/v1/sessions/:id/kill` - -```json -{ - "ok": true, - "accepted": true -} -``` - -Общие ответы при неуспехе используют структурированный конверт ошибки: - -- `404`, когда сессия не существует: - -```json -{ - "error": { - "code": "session_not_found", - "message": "Session was not found.", - "details": { "sessionId": "session-1" } - } -} -``` - -- `409`, когда сессия существует, но не жива: - -```json -{ - "error": { - "code": "session_not_live", - "message": "Session is not live.", - "details": { "sessionId": "session-1" } - } -} -``` - -## Совместимость с comux и мостом OpenClaw - -- comux читает объект `capabilities` из `/health`, чтобы решить, какие функции использовать. -- Мост external OpenClaw bridge plugin OpenClaw (`packages/openclaw-coven`) обновляется в этом репозитории вместе с демоном и использует `apiVersion === "coven.daemon.v1"` как защиту контракта. -- Обновления клиентов для использования курсоров `afterSeq` и пагинированных конвертов событий могут происходить независимо от обновления демона; форма, применяемая демоном, — это источник истины. -- Поле `supportedApiVersions` было удалено из ответа health в `coven.daemon.v1`; клиенты должны проверять `apiVersion` напрямую. - -## Политика совместимости и миграции - -- Клиенты `coven.daemon.v1` могут полагаться на задокументированные имена полей и формы ответов верхнего уровня выше. -- Аддитивные поля обратно совместимы. Клиенты должны игнорировать неизвестные поля, когда это безопасно. -- Любое несовместимое изменение должно выпускаться под новым значением `apiVersion`, предоставляемым `GET /api/v1/health` или его маршрутом-преемником. -- Перед тем как клиент переключится на новый мажорный контракт, репо Coven должен опубликовать обновлённые docs контракта и заметку о миграции, которая отображает старую форму в новую. - -## Рекомендуемый handshake клиента - -1. Вызови `GET /api/v1/health`. -2. Проверь, что `apiVersion === "coven.daemon.v1"` и `capabilities.structuredErrors === true`. -3. Проверь `capabilities.eventCursor === "sequence"` перед использованием пагинации `afterSeq`. -4. Только после этого полагайся на задокументированные формы sessions/events в `v1`. - -## Граница области - -Контракт `coven.daemon.v1` покрывает health демона, обнаружение capabilities, маршрутизацию действий, sessions, events, живой input и живой kill. Не считай будущие имена маршрутов оркестрации, handoff или маршрутизации задач зарезервированным API, пока они не реализованы и не задокументированы в этом файле. diff --git a/docs/ru/API.md b/docs/ru/API.md deleted file mode 100644 index 9ad1fd61..00000000 --- a/docs/ru/API.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Локальный socket API Coven" -description: "Локальный HTTP API Coven, обслуживаемый через Unix socket: health, capabilities, actions, sessions, events и пересылка input под /api/v1." ---- - -# Локальный API Coven - -_Последнее обновление: 2026-05-09_ - -Coven предоставляет небольшой HTTP API через локальный Unix socket по адресу `/coven.sock`. Демон на Rust — это граница авторитета: клиенты могут валидировать для UX, но демон всё равно валидирует корни проекта, cwd, id harness'а, id сессии, input и состояние живой сессии перед действием. - -```mermaid -flowchart LR - Client[Local client] -->|connect| Sock["/coven.sock"] - Sock -->|HTTP/1.1| Router["/api/v1 router"] - Router --> Health["/health"] - Router --> Capabilities["/capabilities"] - Router --> Actions["/actions"] - Router --> Sessions["/sessions[/:id[/input|/kill]]"] - Router --> Events["/events"] - Router --> Version["/api-version"] - - Health & Capabilities & Actions & Sessions & Events & Version -->|"{ ... } or { error: { code, message, details } }"| Client -``` - -Каждый маршрут возвращает либо задокументированную форму успеха, либо структурированный конверт ошибки. Неизвестные маршруты, неизвестные id действий и неизвестные версии API — все отказываются в закрытом виде с `invalid_request` или `not_found`. - -См. [Аутентификация и локальный доступ](/AUTH) для текущей позы auth. Кратко: API демона сегодня не использует OAuth, JWT, bearer-токены, API-ключи или cookies. Доступ основан на локальном Unix-socket, учётные данные провайдера остаются с CLI harness'ов, а любое удалённое, браузерное или TCP-предоставление требует отдельного дизайна auth. - -## Версионирование - -Текущий публичный контракт API — это именованный контракт **`coven.daemon.v1`**, обслуживаемый под префиксом маршрута `/api/v1`. - -Версионированные клиенты должны использовать префикс `/api/v1`: - -| Endpoint | Назначение | -|---|---| -| `GET /api/v1/api-version` | Прочитать активную версию API и поддерживаемые версии | -| `GET /api/v1/health` | Проверить здоровье и метаданные демона | -| `GET /api/v1/capabilities` | Обнаружить capabilities демона/плоскости управления и подсказки политики | -| `POST /api/v1/actions` | Маршрутизировать действие плоскости управления в форме политики | -| `GET /api/v1/sessions` | Перечислить активные сессии | -| `POST /api/v1/sessions` | Запустить сессию | -| `GET /api/v1/sessions/:id` | Получить одну сессию | -| `GET /api/v1/events?sessionId=...` | Прочитать события сессии | -| `POST /api/v1/sessions/:id/input` | Переслать input в живую сессию | -| `POST /api/v1/sessions/:id/kill` | Убить живую сессию | - -Неверсионированные маршруты в настоящее время остаются как legacy-алиасы в течение раннего окна MVP, но новые клиенты не должны на них полагаться. - -Неизвестные префиксы `/api//...` отказываются в закрытом виде с JSON-ответом `unsupported API version`. - -## Ответ health - -`GET /api/v1/health` возвращает версию API вместе со статусом демона: - -```json -{ - "ok": true, - "apiVersion": "coven.daemon.v1", - "covenVersion": "0.0.0", - "capabilities": { - "sessions": true, - "events": true, - "eventCursor": "sequence", - "structuredErrors": true - }, - "daemon": { - "pid": 12345, - "startedAt": "2026-05-09T12:00:00Z", - "socket": "/Users/example/.coven/coven.sock" - } -} -``` - -Когда метаданные демона недоступны, `daemon` равен `null`. - -## Capabilities плоскости управления - -`GET /api/v1/capabilities` — это точка обнаружения для first-party клиентов, таких как клиент чата/ввода. Возвращает id capabilities, владение адаптера, доступность, подсказки политики и id действий. Это предотвращает hardcoding клиентов того, что может делать демон. - -```json -{ - "capabilities": [ - { - "id": "coven.control.actions", - "label": "Coven control-plane action router", - "adapter": "coven-daemon", - "status": "available", - "policy": "allow", - "actions": ["coven.capabilities.refresh"] - }, - { - "id": "desktop.automation", - "label": "Desktop automation adapters", - "adapter": "desktop-use", - "status": "planned", - "policy": "requiresApproval", - "actions": [] - } - ] -} -``` - -## Действия плоскости управления - -`POST /api/v1/actions` принимает конверт intent в стиле клиента чата/ввода. Демон маршрутизирует только известные действия; неизвестные действия отказываются в закрытом виде до того, как любой адаптер сможет выполниться. - -```json -{ - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "args": {} -} -``` - -Безопасные действия, завершённые немедленно, возвращают `200` с payload в форме события, который клиенты могут отрисовать оптимистично или встроить в более поздние потоки событий: - -```json -{ - "ok": true, - "accepted": true, - "action": "coven.capabilities.refresh", - "status": "completed", - "event": { - "kind": "capabilities.refreshed", - "action": "coven.capabilities.refresh", - "origin": "external-client", - "intentId": "intent-1", - "payload": { "capabilities": 3 } - } -} -``` - -## Правила совместимости - -- Дополнительные поля JSON разрешены в ответах `v1`. -- Существующие обязательные поля не должны удаляться или переименовываться внутри `v1`. -- Изменения формы ответа или поведения, нарушающие совместимость, требуют нового префикса версии API. -- Внешние клиенты должны вызывать `/api/v1/health` перед предположением о совместимости. -- Изменения демона, влияющие на поведение `/api/v1/health`, `/api/v1/sessions`, `/api/v1/events`, input или kill, должны обновлять тесты совместимости клиента в том же репозитории. diff --git a/docs/ru/ARCHITECTURE.md b/docs/ru/ARCHITECTURE.md deleted file mode 100644 index 4739b21e..00000000 --- a/docs/ru/ARCHITECTURE.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "Архитектура среды выполнения Coven" -summary: "Как Rust-демон, CLI, TUI, кокпит comux и плагин OpenClaw в Coven компонуются вокруг локального socket API, PTY-адаптеров и хранилища событий." -read_when: - - Понять топологию среды выполнения Coven - - Спроектировать клиент вокруг локального socket API -description: "Как Rust-демон, CLI, TUI, кокпит comux и плагин OpenClaw в Coven компонуются вокруг локального socket API, PTY-адаптеров и хранилища событий." ---- - -# Архитектура Coven - -Coven — это локально-ориентированная подложка для harness-сессий. Rust CLI/демон является слоем авторитета; такие клиенты, как TUI CLI, comux и опциональный плагин OpenClaw, являются слоями представления/интеграции. - -Версионированный контракт локального socket API находится в [`docs/API-CONTRACT.md`](/API-CONTRACT). Клиенты должны использовать `GET /api/v1/health` и согласовывать `apiVersion: "coven.daemon.v1"` и объект `capabilities` перед тем, как полагаться на формы ответов сессий или событий. Все ответы об ошибках используют структурированный конверт `{ error: { code, message, details } }`, описанный там. - -## Топология среды выполнения - -```mermaid -flowchart LR - User[Developer] --> CLI[coven CLI / TUI] - CLI -->|direct commands| Rust[Coven Rust CLI] - Rust --> Daemon[Coven daemon] - - Comux[comux cockpit] -->|HTTP over Unix socket| Daemon - OpenClaw[OpenClaw] --> Plugin[external OpenClaw bridge plugin] - Plugin -->|HTTP over Unix socket| Daemon - ChatClient[chat/intent client] -->|capabilities + actions| Daemon - - Daemon --> Control[Control plane: capability discovery + action routing] - Control --> Policy[Policy + permission hints] - Control --> AdapterBus[Adapter/event bus] - AdapterBus -. desktop automation .-> DesktopUse[desktop-use adapters] - - Daemon --> Boundary[Project-root + cwd guard] - Boundary --> Adapter[Harness adapter router] - Adapter --> Codex[Codex PTY] - Adapter --> Claude[Claude Code PTY] - Adapter -. future .-> Future[Hermes / Aider / Gemini / custom adapters] - - Daemon --> Store[(SQLite session ledger)] - Daemon --> Events[(append-only event log)] - Codex --> Events - Claude --> Events -``` - -## Жизненный цикл сессии - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI/TUI - participant D as Rust daemon - participant S as SQLite store - participant H as Harness PTY - - U->>C: coven run codex "fix tests" - C->>D: POST /api/v1/sessions(projectRoot, cwd, harness, prompt) - D->>D: canonicalize projectRoot + cwd - D->>D: reject outside-root or unsupported harness - D->>S: create session metadata - D->>H: spawn validated argv in PTY - H-->>S: output / exit events - D-->>C: session id + running status - - U->>C: coven sessions - C->>S: list active sessions, or all with --all - C-->>U: interactive session browser - - U->>C: Rejoin / View Log / Summon / Archive / Sacrifice - C->>D: attach/input/kill when live - C->>S: archive/summon/sacrifice non-live session rituals -``` - -## Граница авторитета - -```mermaid -flowchart TD - Client[CLI, TUI, comux, OpenClaw plugin] --> Request[Launch / input / kill / list request] - Request --> Rust[Rank 0 authority: Rust daemon] - Rust --> RootCheck{projectRoot explicit?} - RootCheck -- no --> RejectRoot[Reject] - RootCheck -- yes --> CwdCheck{cwd canonicalized inside root?} - CwdCheck -- no --> RejectCwd[Reject] - CwdCheck -- yes --> HarnessCheck{harness allowlisted?} - HarnessCheck -- no --> RejectHarness[Reject with install hint] - HarnessCheck -- yes --> Spawn[Spawn harness with argv APIs] - Spawn --> Ledger[Persist session + events] -``` - -## Граница ввода / автоматизации - -Клиент чата/ввода должен оставаться чат-интерфейсом, поверхностью для локального эхо/оптимистичного рендеринга, слоем захвата намерений и небольшим быстрым хостом для ультра-простых локальных действий. Он не должен становиться движком автоматизации. - -Coven — это канонический общий локальный рантайм для переиспользуемой автоматизации, потому что он централизует: - -- владение демоном/процессами -- решения по политике и разрешениям -- хранение конфигурации/профилей -- обнаружение возможностей -- маршрутизацию действий и эмиссию событий -- владение адаптерами для Accessibility, AppleScript, клавиатуры/мыши, окон, файловой системы, буфера обмена и мостов к конкретным приложениям - -Предполагаемый поток таков: - -```text -user -> chat/intent client -> Coven -> adapters -> desktop/apps -desktop/apps -> Coven -> chat/intent client UI updates -``` - -`GET /api/v1/capabilities` позволяет клиенту чата/ввода и другим клиентам обнаружить, что Coven может маршрутизировать. `POST /api/v1/actions` даёт клиентам стабильный конверт намерений без жёсткой связки с хрупкими API автоматизации ОС. - -## Граница будущих адаптеров - -Текущий публичный рантайм Coven — один harness на сессию. Демон уже удерживает правильную нижнеуровневую границу для будущей работы по координации: клиенты могут обнаруживать возможности, запускать известные harness'ы, читать события и сохранять обеспечение project-root в Rust. - -Не документируйте будущие команды оркестрации как пользовательские, пока они не появятся в CLI и в socket API. Будущие слои координации должны строиться поверх текущего контракта сессий/событий, не обходя валидацию демона. - ---- - -## Текущая пользовательская поверхность - -- `coven` и `coven tui` открывают дружелюбную для новичков палитру slash-команд. -- `coven doctor` проверяет готовность store/проекта/harness и печатает следующие шаги. -- `coven daemon start/status/restart/stop` управляет локальным демоном. -- `coven run codex|claude ` запускает PTY-сессию с областью видимости проекта. -- `coven sessions` открывает человекочитаемый браузер сессий в терминале; `--plain` сохраняет вывод, пригодный для скриптов. -- Действия в браузере сессий показывают читаемые варианты: **Rejoin**, **View Log**, **Summon**, **Archive** и **Sacrifice**. -- `coven attach|summon|archive|sacrifice ` остаются явными низкоуровневыми глаголами для скриптов и рабочих процессов копирования/вставки. - -## Сводка по дистрибуции - -Wrapper-пакеты npm публикуются для ранних адоптеров: - -- `@opencoven/cli` -- `@opencoven/cli-macos` -- `@opencoven/cli-linux-x64` -- `@opencoven/cli-windows` для Windows x64 - -Версии исходных пакетов остаются шаблонными в репозитории; release workflow dispatch предоставляет публикуемую версию и собирает пакеты платформ. Проверьте реестр npm и GitHub releases, прежде чем делать утверждения о конкретных версиях релизов. diff --git a/docs/ru/AUTH.md b/docs/ru/AUTH.md deleted file mode 100644 index 05ea4988..00000000 --- a/docs/ru/AUTH.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Аутентификация и локальный доступ" -description: "Coven использует доступ через локальный Unix socket в рамках одного пользователя вместо OAuth и API-ключей: что защищает /api/v1 и когда нужен удалённый доступ." ---- - -# Аутентификация и локальный доступ - -_Последнее обновление: 2026-05-14_ - -В Coven сегодня нет аутентификации пользователя на уровне демона в смысле OAuth, JWT, bearer-токена, API-ключа, cookie браузера или хостовой учётной записи. - -Текущее решение — это **модель локального доступа в рамках одного пользователя**: - -- Демон предоставляет HTTP только через локальный Unix socket по адресу `/coven.sock`. -- Путь socket по умолчанию — `~/.coven/coven.sock`. -- Клиенты могут валидировать запросы для UX, но демон на Rust — это граница применения. -- Учётные данные провайдера harness'а остаются в нормальном локальном потоке auth провайдера harness'а. -- Coven не должен читать, проксировать, сохранять или выпускать учётные данные Codex, Claude Code, OpenAI, Anthropic, GitHub или OpenClaw. - -Это намеренно local-first MVP-поза. Она подходит для локальных клиентов того же пользователя, таких как CLI/TUI Coven, comux, клиент чата/ввода и внешний OpenClaw-плагин. Это не схема auth для удалённого API. - -```mermaid -flowchart LR - subgraph User["Same-user trust zone"] - direction LR - CLI[coven CLI / TUI] - Comux[comux] - Plugin["OpenClaw bridge\nOpenClaw plugin"] - Other[Other same-user clients] - end - - CLI -->|Unix socket| Socket["/coven.sock"] - Comux -->|Unix socket| Socket - Plugin -->|Unix socket + trust-anchor checks| Socket - Other -->|Unix socket| Socket - - Socket --> Daemon["Rust daemon\n(authority boundary)"] - Daemon --> Store[("SQLite store + event log")] - Daemon --> PTY[Harness PTYs] - - Remote((Remote network)) -.-x|"REJECTED: no TCP, no auth design"| Daemon - Browser((Browser tab)) -.-x|"REJECTED: no origin policy"| Daemon - OtherUser((Another OS user)) -.-x|"REJECTED: socket permissions"| Daemon -``` - -Граница — это разрешения файловой системы плюс локальность процессов того же пользователя. Всё, что находится за пределами пунктирной зоны, отклоняется по дизайну; введение удалённой, браузерной или меж-пользовательской поверхности требует отдельного дизайна auth (а не туннеля существующего socket). - -## Что защищает API сегодня - -### Локальность Unix socket - -API не предоставляется как TCP по умолчанию. Клиенты подключаются к локальному Unix socket, принадлежащему каталогу состояния Coven пользователя. - -Новые клиенты должны рассматривать путь socket как якорь доверия и должны подключаться только к версионированному API под `/api/v1/...`. - -### Проверки авторитета на Rust - -Демон должен перепроверять чувствительные поля запроса перед действием, даже когда клиент уже их валидировал: - -- версия API; -- корень проекта; -- рабочий каталог; -- id harness'а; -- id сессии; -- состояние живой сессии; -- запросы input; -- запросы kill; и -- id действий плоскости управления. - -Неизвестные версии API, неизвестные id действий, неподдерживаемые harness'ы, недействительные id сессий и рабочие каталоги вне корня должны отказываться в закрытом виде. - -### Auth провайдера, принадлежащий harness'у - -Coven запускает поддерживаемые локальные CLI harness'ов. Он не реализует логин провайдера. - -Примеры: - -- Аутентификация Codex остаётся `codex login` или собственной локальной настройкой CLI Codex. -- Аутентификация Claude Code остаётся `claude doctor` или собственной локальной настройкой CLI Claude Code. - -`coven doctor` может сообщать подсказки по настройке для этих инструментов, но Coven не владеет их учётными данными. - -### Защитные меры внешнего OpenClaw-плагина - -Интеграция OpenClaw вынесена через external OpenClaw bridge plugin. Ядро OpenClaw не является корнем доверия Coven. - -Плагин отключён по умолчанию и должен быть явно выбран как ACP-backend. Он валидирует якорь доверия локального socket перед подключением: - -- `covenHome` должен быть абсолютным каталогом без symlink. -- `socketPath` ограничен `/coven.sock`. -- Путь socket не должен быть symlink. -- Разрешённый socket должен быть Unix socket. -- Корень socket, каталог socket и socket должны принадлежать текущему пользователю. -- Корень socket и каталог не должны быть доступны группе или всем. -- Путь socket помечается отпечатком вокруг подключения, чтобы поймать гонки замены. - -Эти проверки на стороне клиента улучшают глубокую защиту. Они не заменяют применение демона на Rust. - -## Что это не есть - -Текущее решение auth — это не: - -- OAuth; -- OpenID Connect; -- JWT-сессии; -- auth с bearer-токеном; -- auth с API-ключом; -- auth с cookie браузера; -- RBAC; -- многопользовательская авторизация; -- политика CSRF/origin; -- граница облачной учётной записи; ни -- разрешение предоставлять socket API на localhost TCP, удалённой сети или странице браузера. - -Если будущий дашборд, мобильное приложение, удалённый мост или браузерный сервис должен разговаривать с Coven, ему нужен явный дополнительный дизайн auth и pairing. Не туннелируй и не проксируй сырой socket демона в сетевой сервис и не называй это аутентифицированным. - -## Текущий пробел в hardening - -TypeScript-клиент OpenClaw-плагина уже выполняет строгую валидацию якоря доверия socket. - -Демон на Rust в настоящее время владеет применением запросов и поведением socket API, но проверки приватной собственности и разрешений `COVEN_HOME` на стороне Rust перед созданием, привязкой или удалением состояния демона остаются приоритетом hardening. Пока это не реализовано, валидацию socket на стороне клиента следует рассматривать как глубокую защиту для сотрудничающих клиентов, а не как полную границу auth на стороне демона. - -Перед широким распространением Rust должен отказываться в закрытом виде, когда: - -- `COVEN_HOME` не принадлежит текущему пользователю; -- `COVEN_HOME` доступен группе или всем; -- `COVEN_HOME` разрешается через symlink; -- путь socket разрешается вне `COVEN_HOME`; -- существующий путь socket — это symlink или не-socket файл; или -- создание или очистка socket пересечёт границу доверенного каталога состояния. - -## Требования для новых клиентов - -Новые клиенты Coven должны: - -- использовать маршруты `/api/v1/...`; -- вызывать `GET /api/v1/health` перед предположением о совместимости; -- рассматривать демон на Rust как границу авторитета; -- хранить учётные данные провайдера в потоке auth провайдера или harness'а; -- избегать хранения секретов репозитория, дампов окружения, приватных URL или логов, несущих токены; -- отвергать настраиваемые пути socket, которые не разрешаются в `/coven.sock`; -- отказываться в закрытом виде при неизвестных id harness'ов или неподдерживаемых версиях API; и -- избегать добавления любого сетевого, браузерного или удалённого транспорта без отдельного дизайна auth. diff --git a/docs/ru/CLIENT-INTEGRATION.md b/docs/ru/CLIENT-INTEGRATION.md deleted file mode 100644 index 70737949..00000000 --- a/docs/ru/CLIENT-INTEGRATION.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: "Руководство по интеграции клиентов" -description: "Как comux, OpenClaw и другие клиенты должны разговаривать с socket API демона Coven, не дублируя политику или авторитет runtime." ---- - -# Руководство по интеграции клиентов - -Coven — это runtime-подложка. Клиенты должны представлять, маршрутизировать и наблюдать за работой, не захватывая границу авторитета. - -## Правило интеграции - -Разговаривай с Coven через локальный socket API. Не дублируй политику Coven по пути, harness'у, живой сессии или удалению таким образом, который может разойтись с демоном. - -Рекомендуемый handshake: - -1. Вызови `GET /api/v1/health`. -2. Подтверди, что `apiVersion === "coven.daemon.v1"` и нужные поля `capabilities` доступны. -3. Вызови `GET /api/v1/capabilities`, если используешь действия плоскости управления. -4. Используй только версионированные маршруты `/api/v1/...`. - -```mermaid -sequenceDiagram - participant Client - participant Daemon - - Client->>Daemon: GET /api/v1/health - alt daemon unreachable - Daemon--xClient: connection refused - Client->>Client: show "coven daemon start" hint - else apiVersion != coven.daemon.v1 - Daemon-->>Client: 200 { apiVersion: "coven.daemon.v2" } - Client->>Client: show "update Coven or client" hint - else compatible - Daemon-->>Client: 200 { apiVersion: "coven.daemon.v1", capabilities } - Client->>Daemon: GET /api/v1/capabilities (if using actions) - Daemon-->>Client: capability catalog - Client->>Daemon: GET /api/v1/sessions ... - Daemon-->>Client: SessionRecord[] - end -``` - -Клиенты должны рассматривать handshake как **обязательный перед любым другим запросом**. Пропуск его означает зависимость от неопределённых форм ответа от будущей версии демона. - -## Обязанности клиента - -Клиенты могут владеть: - -- навигацией; -- панелями; -- UI чата или приёма; -- формами задач; -- поверхностями diff/review; -- отрисовкой уведомлений; -- выбором сессии; -- оптимистичным локальным состоянием UI; и -- UX одобрения пользователя. - -Клиенты не должны быть единственной точкой применения для: - -- границ корня проекта; -- ограничений cwd; -- allowlist'ов harness'ов; -- проверок живой сессии; -- правил разрушительного удаления; -- доверия socket; -- одобрений внешних действий. - -## comux - -comux — это кокпит-слой. - -Хорошие обязанности comux: - -- перечислять сессии Coven; -- запускать сессии из видимого контекста проекта/worktree; -- открывать сессии в панелях; -- подключаться/возобновлять живую работу; -- читать `coven sessions --json` для простого локального обнаружения, когда управление на уровне демона не нужно; -- показывать логи и артефакты; -- помогать просматривать diff'ы; -- помогать делать merge, PR, архивировать или явно очищать. - -comux должен оставаться полезным, когда Coven не установлен. Если Coven отсутствует, представляй понятные состояния установки и fallback вместо того, чтобы предполагать, что демон существует. - -## Плагин OpenClaw - -Интеграция OpenClaw принадлежит внешнему пакету external OpenClaw bridge plugin, а не ядру OpenClaw. - -Плагин должен: - -- регистрировать опциональный backend Coven; -- валидировать конфиг для UX; -- подключаться к локальному socket; -- запускать сессии через `POST /api/v1/sessions`; -- отображать события Coven в runtime-события OpenClaw; -- сохранять поведение fallback только при явной конфигурации; и -- рассматривать демон на Rust как авторитет запуска. - -Плагин не должен: - -- обходить демон для запусков; -- зависеть от внутренностей ядра OpenClaw; -- хранить учётные данные провайдера; -- предполагать, что неверсионированные маршруты стабильны; или -- расширять разрешения корня проекта. - -## Поверхности ввода и приёма - -Клиенты чата/ввода лучше всего рассматривать как слои приёма и представления. - -Полезные обязанности: - -- захват намерения пользователя; -- показ локального статуса; -- представление одобрений; -- отображение уведомлений; -- передача работы в Coven; -- показ обновлений сессии из Coven. - -Избегай превращения клиентов приёма в движок автоматизации. Переиспользуемая автоматизация должна жить за capabilities и actions Coven, чтобы граница политики оставалась централизованной. - -## Десктоп-клиенты и контрольные комнаты - -Нативная контрольная комната может облегчить эксплуатацию Coven, показывая: - -- активные сессии; -- архивные сессии; -- здоровье демона; -- корни проектов; -- доступность harness'ов; -- интеграции клиентов; -- каталог capabilities; -- очередь одобрения действий; -- логи и трассы; -- ссылки на docs и troubleshooting. - -Используй `coven sessions --json` для активных сессий и `coven sessions --json --all`, когда клиенту также нужны архивные записи. CLI возвращает объект верхнего уровня с массивом `sessions`, и каждая запись использует те же имена полей `SessionRecord`, что и API демона, включая `project_root`, `status`, `created_at`, `updated_at` и nullable `archived_at`. - -Контрольная комната должна по-прежнему использовать тот же socket API и тот же handshake capabilities, что и другие клиенты. - -## Адаптеры десктоп-автоматизации - -Десктоп-автоматизация полезна, когда у приложения нет чистого API. Она также достаточно мощна, чтобы нуждаться в чёткой политике. - -Рекомендуемый шаблон: - -```text -user request - -> client captures intent - -> Coven exposes capability and policy hints - -> client asks for approval when required - -> Coven routes a known action id - -> adapter performs the local UI action - -> event/result returns to the client -``` - -Не позволяй UI-клиентам напрямую связываться с библиотеками автоматизации ОС и потом называть это "интеграцией Coven". Переиспользуемой границей должна быть плоскость управления Coven. - -## Ожидания совместимости - -Для каждой интеграции: - -- используй `/api/v1`; -- сначала вызывай health; -- игнорируй неизвестные аддитивные поля, когда это безопасно; -- отказывайся в закрытом виде при неизвестном требуемом поведении; -- тестируй против репрезентативных ответов демона; -- обновляй `docs/API-CONTRACT.md`, когда меняются формы ответов. - -## Обработка ошибок - -Хороший клиент должен переводить ошибки демона в UI, ориентированный на действие: - -- демон недоступен: показать инструкции старта/перезапуска; -- неподдерживаемая версия API: попросить пользователя обновить Coven или клиент; -- отсутствующий harness: показать руководство `coven doctor`; -- cwd вне корня: объяснить границу проекта; -- сессия не жива: предложить просмотр логов вместо живого input; -- разрушительное действие заблокировано: объяснить, что сессия выполняется или отсутствует подтверждение. diff --git a/docs/ru/COMUX-DEMO-LOOP.md b/docs/ru/COMUX-DEMO-LOOP.md deleted file mode 100644 index 122c2071..00000000 --- a/docs/ru/COMUX-DEMO-LOOP.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Демо-цикл comux и Coven" -description: "Контракт Coven, который делает сессии Codex и Claude Code обнаруживаемыми как видимые панели comux через локальный socket API демона." ---- - -# Демо-цикл comux + Coven - -Это контракт со стороны Coven для того, чтобы сделать сессии Codex и Claude Code, управляемые Coven, видимыми в comux. - -```mermaid -flowchart LR - subgraph Dev["Developer"] - Open[Open repo in comux] - end - - subgraph Local["Local machine"] - Comux[comux cockpit] - CLI[coven CLI] - Daemon[Coven daemon] - PTY1[Codex PTY] - PTY2[Claude PTY] - Store[(SQLite store + events)] - end - - Open --> Comux - Comux -->|discover| CLI - CLI -->|coven sessions --json| Daemon - Daemon --> Store - Daemon --> PTY1 - Daemon --> PTY2 - Comux -->|open / attach| Daemon - Daemon -->|/events| Comux - Comux --> Review[Inspect · Diff · Merge · PR] - Review --> Ritual[Archive · Summon · Sacrifice] - Ritual --> Daemon -``` - -Демо-цикл сквозной: comux никогда не обходит демон, а демон никогда не доверяет comux для применения корня проекта, harness'а или разрушительного удаления. - -## Цикл - -1. Открой целевой репозиторий в comux. -2. При необходимости запусти Coven: - - ```sh - coven daemon start - ``` - -3. Запусти сессию, поддерживаемую Coven, из того же репозитория: - - ```sh - coven run codex "fix the failing tests" - coven run claude "review the diff" - ``` - -4. Позволь comux обнаружить сессии через любой поддерживаемый клиентский путь: - - `coven sessions --json` для простого локального обнаружения по CLI. - - `GET /api/v1/sessions` после `GET /api/v1/health` для клиентов демона. -5. Открой сессию как видимую панель comux или подключись вручную: - - ```sh - coven attach - ``` - -6. Проверяй файлы, diff'ы и вывод сессии из comux. -7. Делай merge, создавай PR, архивируй, призывай, приноси в жертву или явно очищай после проверки. - -## Обнаружение через CLI - -`coven sessions --json` печатает стабильный объект с массивом `sessions`. Записи используют те же snake_case имена полей, что и API демона: - -```json -{ - "sessions": [ - { - "id": "session-1", - "project_root": "/repo", - "harness": "codex", - "title": "Fix the tests", - "status": "running", - "exit_code": null, - "archived_at": null, - "created_at": "2026-05-14T07:00:00Z", - "updated_at": "2026-05-14T07:00:01Z" - } - ] -} -``` - -Используй `--all --json`, когда архивные сессии должны оставаться видимыми. - -## Обнаружение через демон - -Клиенты демона должны использовать версионированный socket API: - -1. `GET /api/v1/health` -2. Проверь `apiVersion === "coven.daemon.v1"` и `capabilities.sessions === true`. -3. `GET /api/v1/sessions` -4. Фильтруй сессии по проверенному корню проекта перед показом их в UI, ограниченном проектом. - -Socket демона по умолчанию использует `~/.coven/coven.sock`. Демон остаётся авторитетом для корней проекта, cwd, id harness'ов, проверок живой сессии, input, запросов kill, состояния архива и правил разрушительного удаления. - -## Состояния недоступности - -Клиенты должны держать свой основной UI пригодным к использованию, когда Coven отсутствует или остановлен: - -- Отсутствует CLI: показать руководство по установке для `@opencoven/cli`. -- Демон остановлен или socket отсутствует: предложить `coven daemon start`. -- Отсутствует harness: предложить `coven doctor`. -- Неподдерживаемая версия API: попросить пользователя обновить Coven или клиент. - -## Roadmap - -Более широкий roadmap OpenCoven остаётся публичной точкой отслеживания сквозной демонстрации: [ROADMAP.md](/ROADMAP). diff --git a/docs/ru/CONCEPTS.md b/docs/ru/CONCEPTS.md deleted file mode 100644 index 0b36d9e0..00000000 --- a/docs/ru/CONCEPTS.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Концепции и терминология Coven" -description: "Определения для существительных, которые Coven использует в CLI, демоне, API и клиентах: harnesses, sessions, projects, rituals, summon и sacrifice." ---- - -# Концепции Coven - -Эта страница определяет существительные, используемые в CLI, демоне, API, docs и интеграциях клиентов Coven. - -```mermaid -flowchart TB - OpenCoven[OpenCoven ecosystem] --> Coven[Coven runtime] - Coven --> Daemon[Daemon] - Daemon --> Project[Project root] - Daemon --> Cwd[Working directory] - Daemon --> Harness[Harness] - Daemon --> Session[Session] - Session --> Event[Event] - Daemon --> Store[Store / SQLite] - Daemon --> Socket[Socket API /api/v1] - Socket --> ControlPlane[Control plane] - ControlPlane --> Capability[Capability] - Socket --> Client[Client] - Session --> Ritual["Rituals: archive / summon / sacrifice"] -``` - -Каждый термин ниже — один узел в графе выше. - -## OpenCoven - -OpenCoven — это экосистема и организация вокруг runtime, кокпита и интеграций. - -Используй **OpenCoven**, когда говоришь о более широком семействе проектов. - -## Coven - -Coven — это локальная runtime-подложка. Она владеет harness-сессиями, ограниченными проектом, PTY, логами, состоянием локального демона и socket API. - -Используй **Coven** для CLI, демона, Rust-крейта, npm-wrapper'а и локального runtime сессий. - -## `coven` - -`coven` — это команда, ориентированная на пользователя. - -Не говори пользователям запускать `opencoven` или `@opencoven`. Имена пакетов живут под `@opencoven/*`, но команда всегда `coven`. - -## Harness - -Harness — это внешний CLI кодирующего агента, который Coven может запускать и контролировать. - -Текущие harness'ы v0: - -- Codex, с id harness'а `codex`. -- Claude Code, с id harness'а `claude`. - -Coven не хранит учётные данные провайдера. Каждый harness продолжает использовать свой собственный локальный поток аутентификации. - -## Корень проекта - -Корень проекта — это явная граница для сессии. Coven валидирует и канонизирует корень проекта перед запуском работы. - -Корень имеет значение, потому что определяет, где harness'у позволено стартовать. Клиент не может расширить эту границу, отправив другой `cwd` или более вольное значение конфигурации. - -## Рабочий каталог - -Рабочий каталог — это каталог запуска для сессии harness'а. Он должен находиться внутри корня проекта после канонизации. - -Примеры: - -```sh -coven run codex "fix tests" -coven run codex "inspect the CLI package" --cwd packages/cli -``` - -Вторая команда действительна только тогда, когда `packages/cli` разрешается внутри выбранного корня проекта. - -## Сессия - -Сессия — это принадлежащая Coven запись одного запуска harness'а. - -Она включает: - -- стабильный id сессии; -- корень проекта; -- id harness'а; -- читаемый заголовок; -- статус; -- опциональный код выхода; -- состояние архива; и -- временные метки создания/обновления. - -Записи сессий хранятся в SQLite. - -## Событие - -Событие — это append-only запись, связанная с сессией. - -События включают записи вывода, выхода и метаданных. Они позволяют клиентам воспроизвести или проверить, что произошло после выхода процесса или перезапуска демона. - -## Демон - -Демон — это локальный процесс на Rust, который владеет состоянием живой сессии и предоставляет API HTTP-поверх-Unix-socket. - -Демон — это граница авторитета. Он валидирует: - -- запросы запуска; -- корни проектов; -- рабочие каталоги; -- id harness'ов; -- живой input; -- запросы kill; и -- id сессий. - -## Хранилище - -Хранилище — это локальная база SQLite Coven. Оно содержит метаданные сессий и append-only историю событий. - -Состояние runtime принадлежит вне системы контроля версий. Не делай commit `.coven/`, баз данных, socket'ов, логов или файлов окружения. - -## Клиент - -Клиент — это всё, что разговаривает с Coven, а не запускает harness'ы напрямую. - -Известные формы клиента: - -- CLI/TUI `coven`. -- Кокпит comux. -- Внешний пакет плагина OpenClaw external OpenClaw bridge plugin. -- Будущие поверхности ввода или десктоп-поверхности приёма. - -Клиенты — это слои удобства, а не корни доверия. - -## Плоскость управления - -Плоскость управления — это слой capabilities и маршрутизации действий перед будущими адаптерами. - -Она позволяет клиентам обнаруживать, что Coven может делать, через `GET /api/v1/capabilities` и отправлять известные действия через `POST /api/v1/actions`. Неизвестные id действий отказываются в закрытом виде. - -## Capability - -Capability описывает функцию, принадлежащую демону или адаптеру, которую клиент может представить. - -Записи capability включают: - -- id; -- метку; -- владеющий адаптер; -- статус; -- подсказку политики; и -- id действий. - -## Ритуалы - -Ритуалы — это удобные для людей глаголы управления сессиями Coven: - -- **Archive** скрывает завершённую сессию из активного списка, сохраняя события. -- **Summon** восстанавливает архивную сессию. -- **Sacrifice** навсегда удаляет не выполняющуюся сессию и её события. - -Имена ритуалов — это продуктовый язык. Безопасное поведение под ними должно оставаться точным и консервативным. - -## Socket API - -Socket API — это публичная граница совместимости для локальных клиентов. - -Текущий стабильный префикс: - -```text -/api/v1 -``` - -Клиенты должны делать handshake с: - -```text -GET /api/v1/health -``` - -перед зависимостью от других форм ответа. diff --git a/docs/ru/GETTING-STARTED.md b/docs/ru/GETTING-STARTED.md deleted file mode 100644 index 9d5f6a00..00000000 --- a/docs/ru/GETTING-STARTED.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Начать работу с Coven" -description: "Установи Coven, запусти первую сессию Codex или Claude Code, ограниченную проектом, и проверь демон, хранилище и harness'ы с помощью coven doctor." ---- - -# Начать работу с Coven - -Это руководство ведёт нового пользователя от свежего checkout или установки npm до видимой сессии агента, ограниченной проектом. - -## Что такое Coven - -Coven — это local-first runtime для harness'ов кодирующих агентов. Он запускает поддерживаемые CLI, такие как Codex и Claude Code, внутри явных границ проекта, записывает метаданные сессии и события и предоставляет работу через CLI, TUI и локальный socket API. - -Короткое обещание: - -> Один проект. Любой harness. Видимая работа. - -## Пути установки - -Используй npm-wrapper, когда нужна самая быстрая публичная установка: - -```sh -npx @opencoven/cli doctor -pnpm dlx @opencoven/cli doctor -``` - -Собирай из исходников, когда вносишь вклад в Coven: - -```sh -git clone https://github.com/OpenCoven/coven.git -cd coven -cargo build --workspace -cargo run -p coven-cli -- doctor -``` - -## Предварительные требования - -Coven требует: - -- Rust stable, если собираешь из исходников. -- Git. -- Unix-подобный локальный runtime для текущего пути socket демона и PTY. -- Хотя бы одну поддерживаемую CLI harness'а в `PATH`. - -Поддерживаемые harness'ы v0: - -- `codex` -- `claude` - -Установи и аутентифицируй harness, прежде чем ожидать, что `coven run` сработает: - -```sh -npm install -g @openai/codex -codex login - -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -## Первый запуск - -Из каталога проекта: - -```sh -coven -``` - -Команда по умолчанию открывает prompt-first TUI. Ты можешь: - -- ввести задачу напрямую и нажать Enter (например, `fix the failing tests` или slash-команду `/run codex fix the failing tests`); -- выбрать пункт меню стрелками или его однобуквенным сокращением и нажать Enter; -- нажать `h` или ввести `/help`, чтобы увидеть примеры на естественном языке и slash-команды; -- нажать `Ctrl+C` или `Esc` для выхода. - -Если предпочитаешь запустить явные проверки настройки: - -```sh -coven doctor -``` - -`coven doctor` проверяет: - -- готовность хранилища; -- обнаружение проекта; -- доступность встроенного harness'а; и -- следующие шаги для отсутствующей настройки. - -## Запустить сессию - -Запусти демон, затем запусти harness-сессию из репозитория или каталога проекта: - -```sh -coven daemon start -coven run codex "fix the failing tests" -``` - -или: - -```sh -coven run claude "polish the CLI help text" -``` - -Для более читаемого списка сессий передай заголовок: - -```sh -coven run codex "update the docs" --title "Docs refresh" -``` - -Используй конкретный рабочий каталог только тогда, когда он внутри обнаруженного корня проекта: - -```sh -coven run codex "inspect this package" --cwd packages/cli -``` - -Coven отвергает рабочие каталоги вне корня. Клиенты могут валидировать для лучшего UX, но демон на Rust — это авторитет. - -## Просмотр сессий - -В интерактивном терминале: - -```sh -coven sessions -``` - -Это открывает браузер сессий. Можно выбрать сессию и выбрать контекстные действия: - -- **Rejoin** для живых сессий. -- **View Log** для завершённых сессий. -- **Summon** для архивных сессий. -- **Archive** для видимых завершённых сессий. -- **Sacrifice** для постоянного удаления не выполняющихся сессий и событий. - -Для скриптов или рабочих процессов copy/paste: - -```sh -coven sessions --plain -coven sessions --all --plain -coven sessions --json -coven sessions --json --all -``` - -## Attach, archive, summon и sacrifice - -Низкоуровневые глаголы сессий остаются доступными: - -```sh -coven attach -coven archive -coven summon -coven sacrifice --yes -``` - -Archive обратим. Summon восстанавливает архивную сессию в активный список. Sacrifice — разрушительный и отказывается от живых сессий. - -## Остановить демон - -```sh -coven daemon stop -``` - -Используй `restart`, когда socket или состояние демона выглядит устаревшим: - -```sh -coven daemon restart -``` - -## Диагностика и облегчение - -`coven pc` — это macOS-first инструмент системной диагностики и облегчения, доступный через CLI Coven. Все операции чтения свободны от побочных эффектов. - -Проверка: - -```sh -coven pc # full report: CPU, memory, disk, top processes -coven pc status # one-line health summary with 🟢/🟡/🔴 indicators -coven pc status --json # machine-readable health summary -coven pc top --n 10 # top-N processes by CPU usage -coven pc disk # disk usage breakdown -``` - -Операции облегчения изменяют состояние системы и требуют явного шлюза `--confirm`: - -```sh -coven pc kill --confirm # SIGTERM with PID identity re-check -coven pc cache clear --confirm # clear ~/Library/Caches + /Library/Caches -``` - -Ограничения безопасности в v1: - -- Все операции записи требуют `--confirm`. Пути обхода нет. -- Завершение — только SIGTERM. Никакого SIGKILL. -- Идентичность процесса перепроверяется непосредственно перед SIGTERM, чтобы предотвратить переиспользование PID. -- Очистка кэша использует жёстко закодированный список путей. Без glob-расширения. -- Аргументы процесса по умолчанию редактируются; передай `--verbose`, чтобы их проверить. -- Никакого `sudo`, никакой мутации LaunchAgent, никакого контроля системных сервисов. - -## Сквозной поток - -```mermaid -flowchart LR - Install["Install\nnpx @opencoven/cli doctor"] --> Doctor["coven doctor"] - Doctor --> Daemon["coven daemon start"] - Daemon --> Run["coven run codex prompt"] - Run --> Sessions["coven sessions\n(rejoin / view log / archive)"] - Sessions --> Sacrifice["coven sacrifice id --yes\n(when done)"] - - Doctor -. on failure .-> Harness["Install harness CLI\n+ provider login"] - Harness --> Doctor -``` - -Цикл "install → doctor → daemon → run → sessions" — это весь счастливый путь для первой сессии. Всё остальное в этом руководстве — fallback или troubleshooting. - - -## Цикл проверки контрибьютора - -Перед открытием PR: - -```sh -cargo fmt --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace --locked -python scripts/check-secrets.py -``` - -Для изменений демона/сессии также запусти smoke-тест: - -```sh -cargo test -p coven-cli --test smoke -- --nocapture -``` - -Smoke-тест использует временный `COVEN_HOME` и фейковый исполняемый файл harness'а. Он не требует приватных учётных данных harness'а. diff --git a/docs/ru/GLOSSARY.md b/docs/ru/GLOSSARY.md deleted file mode 100644 index cfa8d56e..00000000 --- a/docs/ru/GLOSSARY.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Глоссарий Coven" -description: "Определения терминов Coven: ACP, версия API, archive, capability, клиент, comux, harness, корень проекта, ритуал, sacrifice, сессия и summon." ---- - -# Глоссарий - -Как термины сочетаются с первого взгляда: - -```mermaid -flowchart LR - OpenCoven[OpenCoven] --> Coven[Coven] - Coven --> CLI[coven CLI / TUI] - Coven --> Daemon[Daemon] - Daemon --> Store[Store / SQLite] - Daemon --> SocketAPI[Socket API] - Daemon --> ControlPlane[Control plane] - ControlPlane --> Capability[Capability] - Daemon --> Harness[Harness] - Harness --> PTY[PTY] - Harness -.->|owns auth| Provider((Provider)) - Daemon --> Session[Session] - Session --> Event[Event] - Session --> Ritual[Rituals: archive / summon / sacrifice] - Client[Client] --> SocketAPI - Client --> Comux[comux] - Client --> Plugin["OpenClaw bridge (OpenClaw plugin)"] -``` - -Определения следуют по алфавиту. - - -## ACP - -Agent Client Protocol. В этом репо ACP появляется как поверхность интеграции для внешних runtime'ов агентов и совместимости с OpenClaw. Сам Coven не является реализацией ACP; внешний плагин OpenClaw отображает между runtime-событиями OpenClaw и сессиями Coven. - -## Версия API - -Именованный контракт совместимости, предоставляемый socket API демона. Текущее стабильное значение: `coven.daemon.v1`. - -## Archive - -Скрыть не выполняющуюся сессию из активного списка, сохраняя её запись и события. - -## Capability - -Обнаруживаемая функция демона или адаптера, возвращаемая `GET /api/v1/capabilities`. - -## Клиент - -Любой процесс или UI, который разговаривает с демоном Coven, включая CLI, comux, клиент чата/ввода или плагин OpenClaw. - -## comux - -Кокпит-слой для видимой работы агентов, панелей, worktree'ов, ревью и потока merge. comux может потреблять сессии Coven, но не является runtime'ом Coven. - -## Плоскость управления - -Слой демона, который предоставляет capabilities и маршрутизирует известные id действий к принадлежащим адаптерам. - -## Coven - -Локальная runtime-подложка OpenCoven и продукт командной строки. - -## `coven` - -Команда, ориентированная на пользователя. - -## `coven pc` - -macOS-first подкоманда системной диагностики и облегчения. Отчитывает CPU, память, диск и top-процессы. Операции записи (kill процесса, очистка кэша) защищены `--confirm`. - -## `COVEN_HOME` - -Локальный каталог, где Coven хранит состояние демон/socket/база данных, когда настроен. Состояние runtime не должно быть commit'нуто в систему контроля версий. - -## Демон - -Локальный процесс на Rust, который владеет состоянием живой сессии и socket API. - -## Событие - -Append-only запись для вывода, выхода или метаданных сессии. - -## Harness - -Поддерживаемая CLI кодирующего агента, которую Coven может запускать и контролировать. - -## OpenCoven - -Более широкая экосистема и организация вокруг Coven, comux и связанных интеграций. - -## Плагин OpenClaw - -Внешний пакет external OpenClaw bridge plugin, который позволяет OpenClaw использовать Coven через socket API. Не является частью ядра OpenClaw. - -## Корень проекта - -Явная граница репозитория или проекта для сессии. - -## PTY - -Псевдотерминал. Coven использует PTY, чтобы harness'ы вели себя как нативные терминальные инструменты, в то время как их вывод по-прежнему может записываться и воспроизводиться. - -## Prompt-first TUI - -Интерфейс по умолчанию `coven` и `coven tui`. Принимает свободный текст задачи или slash-команды, такие как `/run codex `, в качестве input наряду с навигацией по меню стрелками. - -## Облегчение - -Операции стороны записи в `coven pc`, которые изменяют состояние системы (завершение процесса, удаление кэша). Всегда требуют явный флаг `--confirm`. - -## Sacrifice - -Постоянно удалить не выполняющуюся сессию и её события. - -## Сессия - -Принадлежащая Coven запись одного запуска harness'а. - -## Socket API - -Локальный HTTP-поверх-Unix-socket API, предоставляемый демоном. - -## Summon - -Восстановить архивную сессию в активный список и затем воспроизвести/следить за ней. - -## Будущая координация - -Многоhardness handoff и маршрутизация задач не являются текущими публичными функциями CLI/API. Их следует документировать только как работу roadmap, пока они не реализованы. diff --git a/docs/ru/HARNESS-ADAPTERS.md b/docs/ru/HARNESS-ADAPTERS.md deleted file mode 100644 index 32dfa71f..00000000 --- a/docs/ru/HARNESS-ADAPTERS.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Руководство по адаптерам harness'ов" -description: "Форма адаптера harness, которую Coven использует сегодня, требования к новым harness и как Codex, Claude Code и GitHub Copilot CLI ложатся на поверхность адаптера v0." ---- - -# Руководство по адаптерам harness'ов - -Coven поддерживает Codex, Claude Code и GitHub Copilot CLI. Это руководство описывает текущую форму адаптера и планку для добавления большего количества harness'ов. - -## Текущая форма адаптера - -Встроенный адаптер harness'а определяет: - -- стабильный id harness'а Coven; -- метку, ориентированную на пользователя; -- имя исполняемого файла для обнаружения в `PATH`; -- форму аргумента prompt для интерактивного режима; -- форму аргумента prompt для неинтерактивного режима; и -- подсказку установки/аутентификации для `coven doctor`. - -Текущая реализация ожидает, что prompt будет последним аргументом команды после любых фиксированных prefix args. - -## Встроенные harness'ы - -### Codex - -- Id harness'а: `codex` -- Исполняемый файл: `codex` -- Prefix args в интерактивном режиме: нет -- Prefix args в неинтерактивном режиме: `exec --skip-git-repo-check --color never` - -Подсказка по настройке: - -```sh -npm install -g @openai/codex -codex login -``` - -### Claude Code - -- Id harness'а: `claude` -- Исполняемый файл: `claude` -- Prefix args в интерактивном режиме: нет -- Prefix args в неинтерактивном режиме: `--print` - -Подсказка по настройке: - -```sh -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -## Требования к адаптеру - -Перед добавлением нового harness'а подтверди: - -- CLI можно безопасно обнаружить в `PATH`; -- prompt можно передать без интерполяции shell; -- процесс может выполняться из проверенного cwd проекта; -- вывод можно захватить через события PTY/сессии; -- аутентификация остаётся в нормальном локальном потоке провайдера harness'а; -- режимы отказа понятны в `coven doctor`; -- тесты покрывают построение команды и поведение при отсутствии исполняемого файла. - -## Что пока не добавлять - -Избегай универсальных адаптеров произвольных команд, пока у Coven не появится явная политика и поведение одобрения для них. - -Произвольные команды более опасны, чем именованные адаптеры harness'ов, потому что они могут размыть разницу между "запустить кодирующего агента в этом проекте" и "выполнить любую строку, которую отправил клиент". Сохраняй v0 узким. - -## Контрольный список оценки будущего harness'а - -Для кандидата в harness задокументируй: - -- команду установки; -- имя исполняемого файла; -- локальный поток auth; -- команду одноразового prompt; -- интерактивную команду; -- команду возобновления/сессии, если есть; -- режим неинтерактивного вывода; -- нужно ли инъецировать prompt через stdin; -- может ли CLI отключать цвет/управляющие последовательности; -- может ли CLI избегать опасностей quoting shell; -- известные коды выхода; -- минимальный безопасный smoke-тест. - -## Отображение идентичности сессии - -Некоторые harness'ы имеют собственные id upstream-сессий. Id сессии Coven остаётся id локального runtime. - -Если id upstream становятся полезными, храни их как метаданные, а не заменяй собственный id Coven. Клиенты должны иметь возможность полагаться на стабильный id Coven для attach, событий, archive, summon и sacrifice. - -## Предлагаемые этапы зрелости адаптера - -1. **Заметка по исследованию** - задокументировать форму CLI и риски. -2. **Тесты построения команды** - доказать, что построение argv безопасно. -3. **Обнаружение через doctor** - добавить подсказки по установке/auth. -4. **Smoke запуска** - доказать, что сессия может выполняться во временном проекте. -5. **Smoke attach/replay** - доказать, что события можно воспроизводить. -6. **Совместимость с клиентами** - обновить docs и интеграционные тесты. - -Не прыгай из исследования сразу в публичную поддержку. - -```mermaid -flowchart LR - S1["1. Research note\n(public CLI shape + risks)"] --> S2 - S2["2. argv construction tests\n(no shell, prompt last)"] --> S3 - S3["3. coven doctor detection\n(install + auth hints)"] --> S4 - S4["4. Launch smoke\n(temp project, fake creds)"] --> S5 - S5["5. Attach / replay smoke\n(events round-trip)"] --> S6 - S6["6. Client compatibility\n(comux + plugin tests)"] --> Done(["Public support"]) - - style S1 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S2 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S3 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S4 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S5 fill:#3D3547,stroke:#9A8ECD,color:#fff - style S6 fill:#3D3547,stroke:#9A8ECD,color:#fff - style Done fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 -``` - -Harness, пропускающий любой этап, **не** готов к публичной поддержке, даже если кажется, что он работает на машине мейнтейнера. diff --git a/docs/ru/PRODUCT-SPEC.md b/docs/ru/PRODUCT-SPEC.md deleted file mode 100644 index b0e5e053..00000000 --- a/docs/ru/PRODUCT-SPEC.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Спецификация продукта Coven" -description: "Продуктовый тезис Coven, область MVP, направление harness'ов, поверхность CLI/TUI, API демона и план интеграции OpenClaw для локального runtime агентов." ---- - -# Спецификация продукта Coven - -## Продуктовый тезис - -Coven — это Rust-first harness-подложка для запуска кодирующих агентов как сессий, ограниченных проектом, наблюдаемых и подключаемых. Она позволяет разработчикам приводить harness'ы, которым они уже доверяют, в контролируемый локальный runtime вместо принуждения к одному провайдеру агента или UI. - -Полярная звезда: **Один проект. Любой harness. Видимая работа.** - -## Область MVP - -MVP доказывает основной цикл runtime: - -- Отдельный бинарник CLI с именем `coven` -- Локальный демон для контролируемых сессий -- Явные границы корня проекта -- Интерактивное выполнение сессии через PTY -- Постоянство метаданных сессии и событий -- Команды и потоки TUI для запуска, просмотра, повторного подключения, просмотра, архивации, призыва, принесения в жертву и убийства живых сессий через API демона -- Минимальный локальный API для first-party клиентов -- Внешний пакет плагина OpenClaw, который потребляет этот API, не входя в ядро OpenClaw -- Публичное распространение и документация для ранних пользователей - -Вне области MVP: marketplace-плагины, облачная синхронизация, многопользовательская коллаборация, полное переписывание comux, bundled-интеграция ядра OpenClaw или замена OpenClaw. - -## Направление встроенных harness'ов v0 - -Coven v0 должен поставляться со встроенными адаптерами для Codex и Claude Code. Эти адаптеры должны обнаруживать доступность локальной CLI, конструировать команды без интерполяции shell где возможно, запускать harness внутри проверенного `cwd` проекта и предоставлять output/input через PTY-сессии, управляемые Coven. - -UX терминала должен оставаться сосредоточенным на лёгкой команде `coven` и удобном для людей браузере сессий: - -```sh -coven -coven tui -coven run codex "fix tests" -coven run claude "polish this UI" -coven sessions -coven sessions --plain -``` - -В интерактивном терминале `coven sessions` открывает браузер с читаемыми действиями, такими как **Rejoin**, **View Log**, **Summon**, **Archive** и **Sacrifice**, чтобы пользователям не приходилось запоминать id сессий. Plain-вывод остаётся доступным для скриптов и pipes. - -## Будущий путь Hermes и адаптеров - -Hermes и другие harness'ы должны приходить через небольшой контракт адаптера после того, как встроенный путь v0 будет стабилен. Модель адаптера должна поддерживать будущие цели, такие как Hermes, Aider, Gemini, OpenCode и адаптеры пользовательских команд, не требуя от Coven становиться полным marketplace плагинов в MVP. - -## Текущая архитектура - -```mermaid -flowchart LR - User[Developer] --> CLI[coven CLI / TUI] - CLI --> Daemon[Coven Rust daemon] - Comux[comux] --> Daemon - OpenClaw[OpenClaw] --> Plugin[external OpenClaw bridge plugin] - Plugin --> Daemon - Daemon --> Store[(SQLite session ledger)] - Daemon --> Router[Codex / Claude adapter router] - Router --> PTY[Harness PTYs] -``` - -Для более полных диаграмм см. [Диаграммы архитектуры](/ARCHITECTURE). - -## Отношения с comux и OpenClaw - -Coven — это локальная runtime-подложка. comux может стать визуальным кокпитом для панелей и истории сессий, управляемых Coven. OpenClaw может делегировать запуски harness'а, ограниченные проектом, в Coven только через внешний плагин external OpenClaw bridge plugin, а не через bundled-код ядра OpenClaw. Клиент чата/ввода может потреблять статус сессии, приём или уведомления Coven там, где это полезно. - -Coven должен интегрироваться с этими проектами, не принадлежа никому из них: это общая комната, где запускаются harness'ы, а не вся UI или оркестратор. - -## Граница внешнего плагина OpenClaw - -Интеграция OpenClaw вынесена. Репо OpenClaw не должно включать код OpenCoven или Coven, а Coven не должен зависеть от внутренностей OpenClaw. - -Пакет external OpenClaw bridge plugin — это адаптер совместимости: - -- Вызовы ACP-runtime OpenClaw входят в плагин. -- Плагин валидирует конфиг и подключается к локальному socket Coven. -- Демон на Rust перепроверяет корни проекта, cwd, id harness'ов, input и запросы kill. -- Coven запускает и контролирует PTY harness'а. -- Плагин отображает события Coven обратно в события ACP-runtime OpenClaw. - -Это делает socket API контрактом. Версионирование протокола, тесты совместимости и заметки о релизе принадлежат репо Coven и пакету плагина, а не ядру OpenClaw. - -## Публичный с самого начала статус - -Coven публичен сейчас, пока модель безопасности, поведение демона, контракты адаптеров и пользовательский опыт продолжают созревать. Публичная упаковка должна оставаться консервативной, а готовность должна оцениваться по тому, могут ли ранние пользователи надёжно запускать Codex и Claude Code в видимых, подключаемых сессиях, ограниченных проектом. - -## Область MVP с первого взгляда - -```mermaid -flowchart TB - subgraph InScope["In scope for MVP"] - direction TB - Cli["coven CLI / TUI"] - Doc["coven doctor"] - DaemonOps["Daemon lifecycle"] - PrjGuard["Project-root + cwd guard"] - Codex["Codex adapter"] - Claude["Claude Code adapter"] - Pty["PTY sessions"] - Store["SQLite session ledger + events"] - Rituals["Archive / Summon / Sacrifice"] - Api["/api/v1 socket API"] - Plugin["External OpenClaw bridge plugin"] - Docs["Public docs and distribution"] - end - - subgraph OutOfScope["Out of scope for MVP"] - direction TB - Marketplace["Marketplace plugins"] - Cloud["Cloud sync"] - Multi["Multi-user collaboration"] - Rewrite["Full comux rewrite"] - Bundled["Bundled OpenClaw core integration"] - Replace["Replacing OpenClaw"] - end - - InScope -. revisit after MVP .-> OutOfScope -``` - -Граница выше нормативна для v0. Всё в **OutOfScope** записано в roadmap, а не построено в runtime-подложку. - -## Канонические handle сообщества - -Используй эти точные публичные handle/ссылки, когда docs или метаданные пакета Coven упоминают каналы сообщества: - -- Discord: `discord.gg/opencoven` -- X / Twitter: `@OpenCvn` diff --git a/docs/ru/ROADMAP.md b/docs/ru/ROADMAP.md deleted file mode 100644 index bda36f4d..00000000 --- a/docs/ru/ROADMAP.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: "Публичный roadmap OpenCoven" -description: "Публичный roadmap OpenCoven для Coven, comux и интеграций OpenClaw с секциями shipped, now, next и later для локального runtime агентов." ---- - -# Публичный roadmap OpenCoven - -_Последнее обновление: 2026-05-09_ - -Этот roadmap — публичный журнал прогресса для **OpenCoven**, **Coven** и **comux**. - -Он намеренно написан как карта, обращённая к сообществу, а не как лист внутренних обещаний. Элементы перемещаются, когда их проектируют, реализуют, тестируют, выпускают или намеренно вырезают. Даты избегаются, если релиз уже не запланирован. - -## Полярная звезда - -OpenCoven строит local-first рабочее пространство для агентов, где автономные кодирующие harness'ы могут работать внутри явных комнат: - -- **Coven** — это runtime-подложка: harness-сессии в границах проекта, PTY, логи и локальные API. -- **comux** — это кокпит: видимые панели, worktree'ы, дорожки агентов, ритуалы, ревью и поток merge. -- **Интеграции ввода / OpenClaw** — это поверхности приёма и оркестрации, которые могут передавать работу в тот же локальный runtime, не скрывая, что произошло. - -Простое обещание: - -> Один проект. Любой harness. Видимая работа. - -## Как читать этот roadmap - -- **Shipped** означает, что работа существует в публичном коде или публичных артефактах пакета/релиза. -- **Now** означает активную стабилизацию или ближайшую реализацию. -- **Next** означает запланировано после текущего среза стабилизации. -- **Later** означает направленно важно, но не разрешено отвлекать от local-first MVP. -- **Lab** означает экспериментальную работу, которую мы исследуем публично, когда это возможно, но пока не рассматриваем как стабильное обещание. - -## Текущий снимок - -### Coven - -**Статус:** ранний публичный MVP, пригодный для авантюрных local-first разработчиков. - -Shipped: - -- Публичный репо `OpenCoven/coven`. -- CLI-команда на Rust с именем `coven`. -- Удобная для новичков точка входа `coven` / `coven tui`. -- Проверки настройки `coven doctor`. -- Жизненный цикл локального демона: `coven daemon start/status/restart/stop`. -- Охрана границы корня проекта и cwd. -- Встроенные адаптеры harness'ов Codex и Claude Code. -- Сессии `coven run codex|claude ` с PTY-поддержкой. -- Метаданные сессии и журнал событий с поддержкой SQLite. -- Браузер сессий и ритуалы: **Rejoin**, **View Log**, **Summon**, **Archive**, **Sacrifice**. -- Скриптуемый и человекочитаемый вывод сессий: `coven sessions`, `--plain` и `--all`. -- Локальный API HTTP-поверх-Unix-socket для клиентов. -- Версионированный контракт API `coven.daemon.v1` с именованной apiVersion, читаемыми машиной capabilities, структурированными ошибками и монотонными курсорами событий. См. [`docs/API-CONTRACT.md`](/API-CONTRACT). -- Тесты совместимости для внешнего моста OpenClaw против версионированных ответов демона. -- Подсказки восстановления первого запуска для отсутствующих CLI Codex или Claude Code. -- Реальное smoke-покрытие CLI для потоков перезапуска демона, replay attach, kill, archive, summon и sacrifice. -- Верификация установки и проводка релиза для путей npm-пакетов macOS, Linux x64 и Windows x64. -- Опубликованные wrapper-пакеты npm: - - `@opencoven/cli` - - `@opencoven/cli-macos` - - `@opencoven/cli-linux-x64` -- Внешний bridge-пакет OpenClaw сохраняется вне ядра OpenClaw. -- Docs архитектуры, операционной модели, спецификации продукта, бренда и плана MVP. - -Now: - -- Держать выровненными версионированный контракт API демона и работу совместимости внешних клиентов. См. [`docs/API-CONTRACT.md`](/API-CONTRACT). -- Держать публичные docs выровненными с реальной поверхностью CLI/API. - -Next: - -- Превратить контрольный список MVP в связанные issue/milestone в GitHub. - -Later: - -- Универсальный адаптер команд после достаточного реального использования. -- Дополнительные адаптеры harness'ов, такие как Hermes, Aider, Gemini, OpenCode или пользовательские локальные harness'ы. -- Хуки политики/одобрения для чувствительных действий. -- Более богатые артефакты сессии и вложения. -- **Многоhardness оркестрация** (Phase 1-4, TBD timeline): - - Phase 1: Протокол handoff и передача контекста между harness'ами - - Phase 2: Обнаружение capability и интеллектуальная маршрутизация задач - - Phase 3: Многоинстансная координация между harness'ами - - Phase 4: Дашборд аудита и инструменты комплаенса -- Опциональная облачная/командная коллаборация только после того, как локальный runtime станет скучно надёжным. - -### comux - -**Статус:** ранний публичный продукт, полезный как отдельный терминальный кокпит и становящийся первым визуальным клиентом Coven. - -Shipped: - -- Публичный npm-пакет и CLI-команда `comux`. -- tmux-кокпит для видимой параллельной работы. -- Изоляция git worktree на каждую дорожку агента. -- Реестр launcher'ов агентов с несколькими кодирующими CLI. -- Запуски агентов с multi-select. -- Меню панели для потоков inspect, merge, PR, attach и cleanup. -- Браузер файлов, предпросмотр кода и affordance ревью, ориентированные на diff. -- Sidebar проекта, контроль видимости панелей и потоки повторного открытия. -- Ритуалы для повторяемых настроек проекта. -- Docs хуков жизненного цикла и сгенерированная справка по хукам. -- Docs-сайт и публичные README/spec/smoke. -- Видимость сессий Coven и интеграция запуска через локальный путь моста. -- Направление ритуала восстановления OpenClaw начато публично. - -Now: - -- Стабилизировать UX сессий Coven в comux: list, open, launch, attach/rejoin и состояния недоступности. -- Держать comux полезным без установленного Coven. -- Продолжать dogfooding comux-на-comux для гигиены веток/worktree. -- Подтянуть потоки ревью/merge, чтобы вывод агента оставался явным и инспектируемым. - -Next: - -- Продвигать чёткий демо-цикл `comux + Coven`: - 1. Открыть проект в comux. - 2. Запустить сессию Codex или Claude, поддерживаемую Coven. - 3. Наблюдать её как видимую панель/сессию. - 4. Проверять файлы и diff'ы. - 5. Делать merge, PR, archive или явную очистку. -- Добавить публичные issue для шероховатостей, обнаруженных во время dogfooding. -- Улучшить onboarding для tmux, обнаружения CLI агентов и доступности Coven. -- Сделать лёгким генерацию обновлений Discord из shipped-коммитов и issue roadmap. - -Lab: - -- Исследование нативного кокпита macOS. -- Десктоп-ярлыки и более быстрое переключение проектов/сессий. -- Передача приёма с поверхностей ввода в сессии comux/Coven. - -### Путь интеграции OpenClaw / поверхностей ввода - -**Статус:** opt-in направление моста, не bundled в ядро OpenClaw. - -Shipped: - -- Технический spike моста OpenClaw завершён и намеренно припаркован перед слиянием в ядро. -- Направление внешнего плагина external OpenClaw bridge plugin установлено, чтобы ядро OpenClaw оставалось чистым. -- Граница локального socket/API делает Coven слоем авторитета. - -Now: - -- Рассматривать API Coven как границу совместимости. -- Добавить тесты совместимости перед поощрением широкого использования плагина. -- Держать копию о поверхностях ввода/OpenClaw честной: приём и оркестрация сидят над Coven; они не заменяют runtime-подложку. - -Next: - -- Публично задокументировать поддерживаемый путь плагина после приземления версионирования API. -- Добавить демо, показывающее задачу, перемещающуюся из приёма в runtime Coven в ревью comux. - -## Карта milestones - -```mermaid -flowchart LR - A["A. Local runtime foundation\n(mostly shipped)"] --> B["B. Visible cockpit foundation\n(shipped, stabilizing)"] - A --> C["C. Transparent community loop\n(now)"] - B --> D["D. Harness expansion\n(next/later)"] - C --> D - B --> E["E. Intake → runtime → review\n(next/lab)"] - A --> E - D --> F["F. Multi-harness orchestration\n(planned, phased)"] - E --> F - - style A fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 - style B fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825 - style C fill:#C5BDED,stroke:#D4B5FF,color:#1A1825 - style D fill:#3D3547,stroke:#9A8ECD,color:#fff - style E fill:#3D3547,stroke:#9A8ECD,color:#fff - style F fill:#3D3547,stroke:#9A8ECD,color:#fff -``` - -Цветовая кодировка отражает зрелость: заполненный лавандовый — shipped или стабилизируется; контурный сланцевый — next/later. Рёбра показывают направление пререквизита, а не строгий график. - - -## Публичные milestones - -### Milestone A — Основа локального runtime - -Статус: **mostly shipped** - -- [x] Публичный репо и docs -- [x] CLI `coven` -- [x] Безопасность корня проекта -- [x] Адаптеры Codex и Claude -- [x] PTY-сессии -- [x] SQLite-журнал сессий/событий -- [x] Жизненный цикл демона -- [x] Локальный API sessions/events -- [x] Версионированный контракт API -- [x] Тесты совместимости для внешних клиентов - -### Milestone B — Основа видимого кокпита - -Статус: **shipped, stabilizing** - -- [x] Публичный пакет `comux` -- [x] tmux-панели -- [x] git worktree -- [x] реестр launcher'ов агентов -- [x] браузер файлов / ревью diff'ов -- [x] ритуалы -- [x] меню панели, ориентированное на merge и PR -- [x] Видимость сессий Coven -- [ ] Полировка UX attach/rejoin Coven -- [ ] Задокументированное сквозное демо comux + Coven - -### Milestone C — Прозрачный цикл сообщества - -Статус: **now** - -- [x] Документ публичного roadmap -- [ ] Метки GitHub milestone для `roadmap`, `now`, `next`, `later`, `area:coven`, `area:comux`, `good first issue`, `help wanted` -- [ ] Первый публичный пост roadmap в Discord -- [ ] Еженедельная каденция обновлений shipped/building/next -- [ ] Публичная доска issue, связанная из Discord - -### Milestone D — Расширение harness - -Статус: **next/later** - -- [x] Исследование будущих harness'ов начато -- [x] Задокументирован контракт адаптера -- [ ] Дизайн универсального адаптера команд из реального использования -- [ ] Доказательство третьего harness -- [ ] Docs совместимости harness'ов - -### Milestone E — От приёма к runtime к ревью - -Статус: **next/lab** - -- [ ] Приём с поверхностей ввода/OpenClaw создаёт или запрашивает задачу Coven -- [ ] Coven владеет сессией и журналом событий -- [ ] comux показывает сессию для ревью -- [ ] пользователь явно делает merge, PR, archive или удаляет работу - -### Milestone F — Многоhardness оркестрация (Фаза 1-4) - -Статус: **planned, TBD start** - -**Фаза 1: Протокол handoff (недели 1-2)** -- [ ] Дизайн API handoff и реализация TypeScript -- [ ] Формат передачи контекста и валидация -- [ ] Явный handoff harness-к-harness (например, OpenClaw → Claude Code) -- [ ] Журнал handoff (PostgreSQL) -- [ ] Сквозной тест: Cody передаёт ошибку теста Claude для редактирования файла - -**Фаза 2: Обнаружение capabilities и роутер (недели 3-4)** -- [ ] Реестр и объявление capabilities harness'ов -- [ ] Роутер задач: авто-выбор лучшего harness'а -- [ ] Балансировка нагрузки и цепочки fallback -- [ ] Применение SLA и обработка таймаутов -- [ ] Тест: "Fix this bug" автоматически маршрутизируется к лучшему harness'у - -**Фаза 3: Многоинстансная координация (недели 5-6)** -- [ ] Распределённое хранилище контекста (Redis + PostgreSQL) -- [ ] Регистрация harness'а и heartbeat здоровья -- [ ] Маршрутизация по affinity задачи (ограничения ресурсов) -- [ ] Масштабирование до нескольких инстансов Coven на пользователя -- [ ] Тест: локальные + удалённые harness'ы координируются без коллизии - -**Фаза 4: Аудит и наблюдаемость (недели 7-8)** -- [ ] Дашборд аудита: timeline задачи и трасса handoff -- [ ] Экспорт комплаенса (редактированные трассы) -- [ ] Метрики Prometheus и оповещения -- [ ] Полная видимость оркестрированной работы -- [ ] Тест: легал/комплаенс может запрашивать полную историю - -## Модель прозрачности Discord - -Мы должны держать обновления Discord лёгкими и повторяемыми. - -### Предлагаемые каналы - -- `#roadmap` или forum-style канал `Roadmap` для тредов milestone. -- `#dev-updates` для еженедельных сводок. -- `#help-wanted` для конкретных issue, которые члены сообщества действительно могут взять. - -### Шаблон еженедельного обновления - -```md -## OpenCoven weekly update — YYYY-MM-DD - -### Shipped -- ... - -### Building now -- ... - -### Next up -- ... - -### Help wanted -- ... - -### Links -- Roadmap: https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md -- Coven issues: https://github.com/OpenCoven/coven/issues -- comux issues: https://github.com/BunsDev/comux/issues -``` - -### Правила честных обновлений - -- Не обещай даты, если мы уже не в режиме релиза. -- Связывай shipped-работу с коммитами, релизами, issue или docs. -- Маркируй эксперименты как **Lab**, а не делай вид, что это committed пункты roadmap. -- Разделяй **runtime Coven**, **кокпит comux** и **приём с поверхностей ввода/OpenClaw**, чтобы люди понимали архитектуру. -- Предпочитай небольшие публичные issue вместо гигантских расплывчатых задач. -- Проси помощь только тогда, когда у задачи есть чёткое условие принятия. - -## Первый публичный пост в Discord - -```md -We opened a public roadmap for OpenCoven/Coven/comux so progress is easier to follow. - -The short version: -- Coven is the local runtime substrate: project-scoped Codex/Claude sessions, PTYs, logs, daemon API. -- comux is the visible cockpit: tmux panes, worktrees, rituals, review, merge/PR flows. -- The next serious focus is hardening the Coven API contract and polishing the comux + Coven demo loop. - -Roadmap: https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md -Coven: https://github.com/OpenCoven/coven -comux: https://github.com/BunsDev/comux - -We'll start posting lightweight shipped / building / next updates here so the work is easier to follow and easier to help with. -``` diff --git a/docs/ru/SAFETY-MODEL.md b/docs/ru/SAFETY-MODEL.md deleted file mode 100644 index 3c0efaa0..00000000 --- a/docs/ru/SAFETY-MODEL.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: "Модель безопасности Coven" -description: "Local-first граница безопасности Coven: доверяй демону на Rust, рассматривай клиенты как недоверенные и держи учётные данные провайдера harness'а вне runtime." ---- - -# Модель безопасности Coven - -Coven local-first, но локальный не означает безвредный. Он может запускать harness'ы агентов в реальных репозиториях, пересылать input в живые процессы и сохранять логи. Этот документ излагает границы безопасности, которые должны сохранять docs, клиенты и код. - -## Граница доверия - -Демон на Rust — это граница авторитета. - -Каждый клиент недоверен для целей применения, включая: - -- CLI/TUI; -- comux; -- клиенты чата/ввода; -- внешний плагин OpenClaw; -- скрипты; и -- будущие десктоп-клиенты. - -Клиенты могут улучшать UX, но не должны быть единственным местом, где применяется чувствительное решение. - -```mermaid -flowchart TB - subgraph UntrustedZone["Untrusted for enforcement (UX layer only)"] - direction LR - CLI[coven CLI / TUI] - Comux[comux] - ChatClient[chat/intent client] - Plugin["OpenClaw bridge plugin"] - Scripts[Scripts / other clients] - end - - UntrustedZone -->|HTTP over Unix socket| Boundary{{Daemon authority boundary}} - - subgraph TrustedZone["Trusted for enforcement"] - direction TB - Boundary --> ValidateRoot[Canonicalize projectRoot] - ValidateRoot --> ValidateCwd[Canonicalize cwd inside root] - ValidateCwd --> AllowHarness[Allowlist harness id] - AllowHarness --> ValidateSession[Validate session id / liveness] - ValidateSession --> RouteAction[Route action id via control plane] - RouteAction --> Spawn[Spawn argv only — never sh -c] - Spawn --> Store[(SQLite store + append-only events)] - end -``` - -Всё, что находится в **UntrustedZone**, может лгать, расходиться или быть заменено. Всё, что находится в **TrustedZone**, — это работа демона на Rust, и она должна отказываться в закрытом виде при неизвестных. Направление стрелки — единственное направление, в котором разрешено течь чувствительное решение: из недоверенного в границу, где оно перепроверяется. - -## Аутентификация и локальный доступ - -Текущее решение auth Coven — это модель локального доступа в рамках одного пользователя, а не сетевой протокол аутентификации. - -- API демона работает поверх `/coven.sock`, а не TCP. -- В v0 нет OAuth, JWT, bearer-токена, API-ключа, cookie браузера, RBAC или сессии хостовой учётной записи демона. -- Учётные данные провайдера остаются в локальном потоке auth провайдера/harness'а, таком как Codex или Claude Code. -- Клиенты недоверены для применения; демон на Rust должен по-прежнему перепроверять каждый чувствительный запрос. -- Внешний плагин OpenClaw выполняет валидацию якоря доверия socket перед подключением, но проверки приватной собственности и разрешений `COVEN_HOME` на стороне Rust остаются приоритетом hardening. -- Не предоставляй сырой socket API через TCP localhost, страницу браузера, удалённый мост или мобильный pairing-поток без отдельного явного дизайна auth. - -Подробный контракт живёт в [Аутентификация и локальный доступ](/AUTH). - -## Основные правила - -- Запускай только с явным корнем проекта. -- Канонизируй `projectRoot` и `cwd` перед сравнением путей. -- Отвергай рабочие каталоги вне корня проекта. -- Держи id harness'ов в allowlist, пока не появится реальный слой политики. -- Строй команды harness'а с argv API. -- Не выполняй prompt через `sh -c`. -- Держи учётные данные провайдера в потоке аутентификации провайдера или harness'а. -- Рассматривай socket API как локальный контракт продукта, а не приватную деталь реализации. -- Отказывайся в закрытом виде при неизвестных версиях API, неизвестных id действий, неподдерживаемых harness'ах и недействительных id сессий. - -## Данные и секреты - -Coven не должен требовать секретов, хранимых в репозитории. - -Не делай commit состояния runtime: - -- `.coven/` -- `*.sqlite` -- `*.sqlite3` -- `*.db` -- `*.sock` -- `.env*` -- приватные ключи -- сертификаты -- логи, несущие токены - -Docs и примеры должны использовать placeholder'ы, такие как `/path/to/project`, `/Users/example`, `session-1` и `intent-1`. - -## Предостережение журнала событий - -Журнал событий записывает вывод harness'а. Harness может напечатать чувствительные данные, если пользователь просит проверить чувствительный репозиторий или если вывод команды включает секреты. - -Рекомендуемое руководство для пользователя: - -- Не запускай недоверенные prompt в чувствительных репозиториях. -- Не проси harness дампить переменные окружения. -- Не вставляй секреты в prompt. -- Используй одноразовые проекты для демо и smoke-тестов. -- Запускай `python scripts/check-secrets.py` перед публикацией docs, fixtures или артефактов релиза. - -## Поза локального socket - -API демона работает поверх локального Unix socket. Он предназначен для локальных клиентов того же пользователя. - -Приоритеты hardening: - -- приватная собственность и разрешения `COVEN_HOME`; -- безопасное создание и очистка socket; -- ограничения размера запроса; -- таймауты чтения; -- структурированные коды ошибок; -- пагинация событий; и -- тесты совместимости для внешних клиентов. - -## Управление живой сессии - -Запросы живого input и kill требуют действительный id живой сессии. - -Ожидаемое поведение: - -- неизвестный id сессии возвращает not found; -- input/kill к не-живой сессии возвращает conflict; -- разрушительное удаление сессии отказывает выполняющимся сессиям; -- интерактивное удаление требует явного подтверждения. - -## Десктоп-автоматизация и управление локальным UI - -Будущие адаптеры десктоп-автоматизации следует рассматривать как привилегированные локальные capabilities. - -Требуемая поза: - -- обнаруживать capabilities перед показом действий; -- ясно маркировать рискованные действия; -- требовать явное одобрение для кликов, ввода, удаления, отправки, покупки, публикации или модификации внешнего состояния; -- логировать запросы действий и результаты без записи секретов; -- держать адаптеры за плоскостью управления Coven, а не позволять каждому клиенту напрямую связываться с API автоматизации ОС. - -Разделение должно оставаться: - -```text -client intent -> Coven policy/control plane -> adapter -> desktop/app -``` - -## Внешние действия - -Coven должен спрашивать или требовать политику на уровне хоста перед действиями, которые покидают машину или влияют на внешние сервисы, включая: - -- отправку сообщений; -- отправку email; -- публичную публикацию; -- покупку; -- удаление удалённых данных; -- push в git remote; и -- модификацию облачных ресурсов. - -Локальный runtime может сделать эти действия видимыми, но видимость — это не согласие. diff --git a/docs/ru/SESSION-LIFECYCLE.md b/docs/ru/SESSION-LIFECYCLE.md deleted file mode 100644 index c0a7d02f..00000000 --- a/docs/ru/SESSION-LIFECYCLE.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Жизненный цикл сессии" -description: "Как сессия Coven перемещается через состояния created, running, completed, failed, orphaned, archived и summoned от coven run до replay." ---- - -# Жизненный цикл сессии - -Этот документ объясняет, что происходит от `coven run` до завершения, replay, archive, summon и удаления. - -## Состояния жизненного цикла - -Текущее хранилище записывает статус сессии как строку. Распространённые состояния включают: - -- `created` - запись сессии существует до того, как начинается живое выполнение. -- `running` - процесс harness'а активен под надзором демона. -- `completed` - harness вышел успешно. -- `failed` - настройка или запуск не удались до нормального завершения. -- `orphaned` - предыдущий демон остановился, пока сессия всё ещё была помечена как выполняющаяся. - -Состояние archive хранится отдельно как `archived_at`. Завершённую или неуспешную сессию можно скрыть из активного списка без изменения её финального статуса. - -```mermaid -stateDiagram-v2 - [*] --> created: coven run / POST /sessions - created --> running: PTY spawn succeeds - created --> failed: validation fails / PTY spawn errors - running --> completed: harness exits 0 - running --> failed: harness exits non-zero - running --> orphaned: daemon stops while running - - completed --> archived: coven archive - failed --> archived: coven archive - orphaned --> archived: coven archive - - archived --> completed: coven summon (was completed) - archived --> failed: coven summon (was failed) - archived --> orphaned: coven summon (was orphaned) - - completed --> [*]: coven sacrifice --yes - failed --> [*]: coven sacrifice --yes - orphaned --> [*]: coven sacrifice --yes - archived --> [*]: coven sacrifice --yes -``` - -Диаграмма выше нормативна для хранилища v0. `running` сессии нельзя архивировать или приносить в жертву напрямую — убей их или дождись выхода. `created → running` — единственный переход, требующий spawn PTY; каждый другой переход — это изменение состояния только в хранилище, управляемое демоном на Rust. - -## Путь запуска - -Нормальный поток запуска: - -1. Пользователь или клиент отправляет задачу через CLI или локальный API. -2. Coven разрешает корень проекта. -3. Coven канонизирует корень проекта и рабочий каталог. -4. Coven отвергает рабочие каталоги вне корня. -5. Coven проверяет, что id harness'а поддерживается. -6. Coven создаёт запись сессии в SQLite. -7. Демон делает spawn harness'а в PTY с использованием argv API. -8. Данные вывода и выхода записываются как события. -9. Статус сессии и код выхода обновляются. - -Слой Rust выполняет проверки авторитета, даже когда TypeScript-клиент уже валидировал запрос для UX. - -```mermaid -sequenceDiagram - participant Client as Client (CLI / TUI / comux / plugin) - participant Daemon as Coven daemon - participant Store as SQLite store - participant PTY as Harness PTY - - Client->>Daemon: POST /api/v1/sessions { projectRoot, cwd, harness, prompt } - Daemon->>Daemon: canonicalize projectRoot - alt projectRoot invalid - Daemon-->>Client: 400 invalid_request - end - Daemon->>Daemon: canonicalize cwd inside projectRoot - alt cwd outside root - Daemon-->>Client: 400 invalid_request (cwd вне корня проекта) - end - Daemon->>Daemon: lookup harness in adapter table - alt harness unknown - Daemon-->>Client: 400 invalid_request (with install hint) - end - Daemon->>Store: insert session (status=created) - Daemon->>PTY: spawn argv (prefix args + prompt) - alt spawn / initial-write fails - Daemon->>Store: update status=failed - Daemon-->>Client: 500 launch_failed (details.sessionId) - else PTY spawn ok - Daemon->>Store: update status=running - Daemon-->>Client: 200 SessionRecord - PTY-->>Store: append output / exit events - PTY->>Daemon: process exits with code - Daemon->>Store: update status=completed|failed, exit_code - end -``` - -## Отсоединённые записи - -`coven run ... --detach` создаёт запись сессии без запуска harness'а. Это полезно для потоков тестирования и разработки, которым нужна запись журнала без запуска внешнего процесса. - -Отсоединённые записи не должны представляться как завершённая работа агента. - -## Attach и replay - -`coven attach ` воспроизводит известный вывод событий и следит за живым выводом, когда сессия всё ещё активна. - -Для завершённой сессии attach действует как просмотрщик логов. Для выполняющейся сессии attach также пересылает input в живую сессию демона. - -## Поведение браузера сессий - -`coven sessions` выбирает режим вывода на основе контекста: - -- В интерактивном терминале он открывает браузер сессий. -- Когда пайпится или запускается с `--plain`, печатает табличный вывод. -- `--json` печатает читаемые машиной записи сессий для локальных клиентов. -- `--all` включает архивные сессии. -- `--manage` принудительно открывает браузер. - -Браузер предлагает контекстные действия, чтобы пользователям не приходилось запоминать id сессий. - -## Archive - -Archive скрывает не выполняющуюся сессию из активного списка по умолчанию, сохраняя запись сессии и журнал событий. - -```sh -coven archive -``` - -Используй archive для старой работы, которая должна оставаться инспектируемой. - -## Summon - -Summon восстанавливает архивную сессию в активный список и затем воспроизводит/следит за ней: - -```sh -coven summon -``` - -Summon не перезапускает оригинальный prompt harness'а. Он меняет состояние archive и открывает существующую запись. - -## Sacrifice - -Sacrifice навсегда удаляет не выполняющуюся сессию и каскадирует удаление на её события: - -```sh -coven sacrifice --yes -``` - -Команда отказывает живым сессиям. Интерактивный браузер просит пользователя ввести `sacrifice` перед удалением. - -Используй sacrifice только тогда, когда сессия и её логи должны быть удалены из локального журнала. - -## Восстановление осиротевших сессий - -Если демон запускается и обнаруживает сессии, которые были помечены `running` из предыдущей жизни демона, эти сессии помечаются `orphaned`. - -Осиротевшая сессия означает, что Coven больше не владеет живым процессом для этой записи. Журнал событий может всё ещё быть полезен, но операции живого input и kill должны отказывать. - -## Долговечность событий - -События — это append-only записи в SQLite. Это даёт клиентам стабильный источник replay, даже когда оригинальный процесс PTY вышел. - -Не записывай намеренно секреты, дампы окружения, приватные URL или вывод команды, несущий токены, в события. Coven не может гарантировать, что вывод harness'а свободен от секретов, поэтому пользователи должны избегать запуска недоверенных prompt в чувствительных репозиториях. diff --git a/docs/ru/TROUBLESHOOTING.md b/docs/ru/TROUBLESHOOTING.md deleted file mode 100644 index 1d80c686..00000000 --- a/docs/ru/TROUBLESHOOTING.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: "Решение проблем Coven" -description: "Диагностируй проблемы Coven, такие как отсутствующие команды coven, ошибки socket демона, harness не найден, осиротевшие сессии и отказы корня проекта." ---- - -# Решение проблем Coven - -Начни с: - -```sh -coven doctor -``` - -`doctor` — это самый быстрый способ проверить готовность хранилища, проекта, демона и harness'а. - -```mermaid -flowchart TD - Start([Something broken?]) --> Doctor["coven doctor"] - Doctor --> Store{store ok?} - Store -- no --> CovenHome["Check $COVEN_HOME ownership + perms"] - Store -- yes --> Project{project ok?} - Project -- no --> ProjectFix["Run from inside a project tree"] - Project -- yes --> DaemonChk{daemon running?} - DaemonChk -- no --> StartDaemon["coven daemon start / restart"] - DaemonChk -- yes --> Harness{harness detected?} - Harness -- no --> InstallHarness["Install harness CLI\n(see install hint)"] - Harness -- yes --> RunChk{coven run works?} - RunChk -- no --> RunFix["Check provider auth\n(codex login / claude doctor)"] - RunChk -- yes --> AttachChk{attach behavior expected?} - AttachChk -- no --> AttachFix["Session may be archived/orphaned\nUse coven sessions --all"] - AttachChk -- yes --> Done([Working]) - - CovenHome --> Doctor - ProjectFix --> Doctor - StartDaemon --> Doctor - InstallHarness --> Doctor - RunFix --> Doctor - AttachFix --> Doctor -``` - -Следуй неуспешной ветке. Почти каждая проблема в остальной части этой страницы — это одна из этих ветвей подробно. - -## Команда `coven` не найдена - -Если используешь npm: - -```sh -npx @opencoven/cli doctor -pnpm dlx @opencoven/cli doctor -``` - -Если собираешь из исходников: - -```sh -cargo run -p coven-cli -- doctor -``` - -Если ты установил нативный бинарник, убедись, что его каталог в `PATH`. - -## Harness отсутствует - -`coven doctor` печатает подсказки по установке для каждого встроенного harness'а. - -Codex: - -```sh -npm install -g @openai/codex -codex login -``` - -Claude Code: - -```sh -npm install -g @anthropic-ai/claude-code -claude doctor -``` - -Затем повтори: - -```sh -coven doctor -``` - -## Демон недоступен - -Запусти или перезапусти его: - -```sh -coven daemon start -coven daemon status -coven daemon restart -``` - -Если клиент не может подключиться, проверь, что он использует тот же `COVEN_HOME`, что и CLI. - -## Здоровье и давление системы - -Если сессии ощущаются медленными, демон медленно стартует или `coven doctor` успешен, но работа harness'а тормозит, базовая машина может находиться под давлением CPU, памяти или диска. - -`coven pc` показывает локальный отчёт системы без запуска harness'а. Все операции чтения свободны от побочных эффектов: - -```sh -coven pc # full report: CPU, memory, disk, top processes -coven pc status # one-line health summary -coven pc top --n 10 # top-N processes by CPU usage -coven pc disk # disk usage breakdown -``` - -Операции облегчения изменяют состояние системы и требуют явного шлюза `--confirm`: - -```sh -coven pc kill --confirm # SIGTERM with PID identity re-check -coven pc cache clear --confirm # clear ~/Library/Caches + /Library/Caches -``` - -`coven pc` в настоящее время macOS-first. См. [Диагностика и облегчение](GETTING-STARTED.md#diagnostics-and-relief) в Начать для полной справки по командам. - -## Устаревшие выполняющиеся сессии - -Если демон остановился, пока сессии выполнялись, эти записи могут стать `orphaned` при следующем запуске демона. - -Используй: - -```sh -coven sessions --all -``` - -Затем просмотри логи, заархивируй запись или принеси её в жертву, если она больше не полезна. - -## Сессия не принимает input - -Input работает только для живых сессий, принадлежащих демону. - -Если сессия завершена, неуспешна, архивирована или осиротевшая, attach работает как replay/просмотр логов, а не как живой input. - -## `cwd` отвергнут - -Coven отвергает рабочие каталоги, которые разрешаются вне корня проекта. - -Используй путь внутри проекта: - -```sh -coven run codex "inspect package" --cwd packages/cli -``` - -Не используй symlink-трюки или родительские пути, чтобы выйти за границу проекта. - -## Версия API отвергнута - -Новые клиенты должны использовать `/api/v1`. - -Проверь совместимость демона: - -```text -GET /api/v1/health -``` - -Если клиент ожидает более новый API, чем предоставляет демон, обнови Coven или клиент, чтобы их поддерживаемые версии пересекались. - -## `coven sessions` напечатал таблицу вместо открытия браузера - -Coven открывает браузер только в интерактивном терминале. - -Принудительно открыть режим браузера: - -```sh -coven sessions --manage -``` - -Принудительно использовать табличный режим: - -```sh -coven sessions --plain -``` - -## Путаница с archive, summon и sacrifice - -- Archive скрывает не выполняющуюся сессию, но сохраняет события. -- Summon восстанавливает архивную сессию в активный список. -- Sacrifice навсегда удаляет не выполняющуюся сессию и её события. - -Используй интерактивный браузер, когда возможно: - -```sh -coven sessions --all --manage -``` - -## Сбой сканирования секретов - -Запусти: - -```sh -python scripts/check-secrets.py -``` - -Если не удаётся, удали секрет из рабочего дерева. Если секрет попал в историю git, ротируй учётные данные перед перезаписью истории или публикацией. - -Не вставляй найденные значения секретов в issue, логи, docs или чат. - -## Проверки контрибьютора падают после правок только в docs - -Как минимум запусти: - -```sh -python scripts/check-secrets.py -git diff --check -``` - -Для изменений кода запусти полный шлюз: - -```sh -cargo fmt --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace --locked -python scripts/check-secrets.py -``` diff --git a/docs/ru/harnesses/claude-code.md b/docs/ru/harnesses/claude-code.md deleted file mode 100644 index d8c09bfc..00000000 --- a/docs/ru/harnesses/claude-code.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -summary: "Запускай Anthropic Claude Code под надзором Coven. Id harness'а `claude`." -read_when: - - Настройка Claude Code для Coven - - Диагностика специфичных для Claude сбоев harness'а -title: "Harness Claude Code" -description: "Запускай CLI Anthropic Claude Code под надзором Coven с id harness'а claude, PTY, ограниченным проектом, и стандартными потоками attach и ритуалов." ---- - - -Claude Code — это CLI кодирующего агента Anthropic. Coven оборачивает её в PTY, ограниченный проектом, чтобы запуски, attach и ритуалы работали так же, как для любого другого harness'а. - -| Поле | Значение | -|---|---| -| Id harness'а | `claude` | -| Установка | `npm install -g @anthropic-ai/claude-code` | -| Auth | `claude doctor` (одноразово, со стороны Anthropic) | -| Проверка doctor | `coven doctor` сообщает разрешённый путь и версию Claude. | - -## Настройка - - - - ```bash - npm install -g @anthropic-ai/claude-code - ``` - - - ```bash - claude doctor - ``` - Учётные данные провайдера остаются с Claude Code. Coven никогда их не читает. - - - ```bash - coven doctor - ``` - Вывод должен включать `claude: ok (/usr/local/bin/claude)`. - - - ```bash - coven run claude "polish this UI" - ``` - - - -## Флаги для каждой сессии - -```bash -coven run claude "refactor for clarity" --cwd packages/web --title "Web refactor" -``` - -- `--cwd` — канонизирован внутри корня проекта. -- `--title` — задаёт читаемый заголовок в браузере сессий. -- `--json` — печатает структурированные метаданные запуска для клиентов. - -## Граница auth провайдера - -Claude Code владеет собственным потоком OAuth и кэшем токенов. Coven никогда не читает ключи Anthropic или cookies сессии. - -## Решение проблем - -| Симптом | Вероятная причина | Решение | -|---|---|---| -| `coven doctor` сообщает, что `claude` отсутствует | Claude Code не в `PATH` | `npm install -g @anthropic-ai/claude-code`, затем повторно запусти doctor. | -| Claude просит логин | Auth не завершён | `claude doctor`. | -| Сессия показывает долгую паузу pre-flight | Claude разрешает конфигурацию | Только при первом запуске; последующие запуски быстры. | - -## Как Coven контролирует Claude Code - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI - participant D as Coven daemon - participant Cl as Claude PTY - participant An as Anthropic API - - U->>C: coven run claude "refactor for clarity" - C->>D: POST /api/v1/sessions - D->>D: canonicalize root + cwd - D->>D: lookup adapter for "claude" - D->>Cl: spawn claude (prefix: --print for non-interactive, none for interactive) - Cl->>An: provider auth (uses Anthropic local credentials — Coven does not see) - An-->>Cl: model response stream + tool calls - Cl-->>D: stdout / exit events - D-->>C: SessionRecord (id, status=running) - C-->>U: print session id, switch to attach view -``` - -Вызовы инструментов Claude Code выполняются внутри процесса Claude — Coven их не арбитрирует. PTY захватывает их вывод как обычный stdout/stderr. - - -## Связанное - -- [Установка CLI harness'ов](/harnesses/installing) -- [Граница auth провайдера](/harnesses/provider-auth) -- [Решение проблем harness'а](/harnesses/troubleshooting) diff --git a/docs/ru/harnesses/codex.md b/docs/ru/harnesses/codex.md deleted file mode 100644 index 82e7cbc4..00000000 --- a/docs/ru/harnesses/codex.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -summary: "Запускай CLI OpenAI Codex под надзором Coven. Id harness'а `codex`." -read_when: - - Настройка Codex для Coven - - Диагностика специфичных для Codex сбоев harness'а -title: "Harness Codex" -description: "Запускай CLI OpenAI Codex под надзором Coven с id harness'а codex, PTY, ограниченным проектом, и обычными потоками сессии, attach и ритуалов." ---- - - -Codex — это CLI кодирующего агента OpenAI. Coven оборачивает её в PTY, ограниченный проектом, чтобы запуски, attach и ритуалы работали так же, как для любого другого harness'а. - -| Поле | Значение | -|---|---| -| Id harness'а | `codex` | -| Установка | `npm install -g @openai/codex` | -| Auth | `codex login` (одноразово, со стороны OpenAI) | -| Проверка doctor | `coven doctor` сообщает разрешённый путь и версию Codex. | - -## Настройка - - - - ```bash - npm install -g @openai/codex - ``` - Другие методы установки (Homebrew cask, менеджеры пакетов) перечислены в [репо Codex](https://github.com/openai/codex). - - - ```bash - codex login - ``` - Учётные данные провайдера остаются с Codex. Coven никогда их не читает. - - - ```bash - coven doctor - ``` - Вывод должен включать строку вроде `codex: ok (/usr/local/bin/codex)`. - - - ```bash - coven run codex "fix the failing tests" - ``` - - - -## Флаги для каждой сессии - -```bash -coven run codex "audit this repo" --cwd packages/cli --title "CLI audit" -``` - -- `--cwd` — канонизирован внутри корня проекта. -- `--title` — задаёт читаемый заголовок в браузере сессий. -- `--json` — печатает структурированные метаданные запуска для клиентов. - -## Граница auth провайдера - -Codex владеет собственным потоком OAuth и кэшем токенов. Если ты видишь `Invalidated OAuth token`, снова запусти `codex login`. Coven сохранит существующую запись сессии, чтобы ты мог перезапустить с тем же заголовком. - -Для локального пути спасения: - -```bash -coven patch openclaw "fix Codex auth profile order after invalidated OAuth token" -``` - -## Решение проблем - -| Симптом | Вероятная причина | Решение | -|---|---|---| -| `coven doctor` сообщает, что `codex` отсутствует | Codex не в `PATH` | `npm install -g @openai/codex`, затем повторно запусти doctor. | -| Codex просит логин при каждом запуске | Устаревший токен | `codex login`. | -| Сессия зависает при старте | Codex ждёт prompt TTY | Отсоединись с `Ctrl-]`, перезапусти с `coven run` напрямую. | - -## Как Coven контролирует Codex - -```mermaid -sequenceDiagram - participant U as User - participant C as coven CLI - participant D as Coven daemon - participant Cx as Codex PTY - participant Op as OpenAI API - - U->>C: coven run codex "audit this repo" - C->>D: POST /api/v1/sessions - D->>D: canonicalize root + cwd - D->>D: lookup adapter for "codex" - D->>Cx: spawn codex (prefix: exec --skip-git-repo-check --color never) - Cx->>Op: provider auth (uses ~/.codex credentials — Coven does not see) - Op-->>Cx: model response stream - Cx-->>D: stdout / exit events - D-->>C: SessionRecord (id, status=running) - C-->>U: print session id, switch to attach view -``` - -Пунктирная линия, на которую стоит обратить внимание: Coven никогда не подключается к API OpenAI сам. Путь учётных данных — **CLI Codex ↔ OpenAI**, при этом Coven только наблюдает вывод PTY. - - -## Связанное - -- [Установка CLI harness'ов](/harnesses/installing) -- [Граница auth провайдера](/harnesses/provider-auth) -- [Решение проблем harness'а](/harnesses/troubleshooting) diff --git a/docs/ru/harnesses/copilot-cli.md b/docs/ru/harnesses/copilot-cli.md deleted file mode 100644 index bed5d32b..00000000 --- a/docs/ru/harnesses/copilot-cli.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -summary: "Запуск GitHub Copilot CLI под наблюдением Coven. Id harness'а — `copilot`." -read_when: - - Настройка GitHub Copilot CLI для Coven - - Диагностика сбоев harness, специфичных для Copilot -title: "Harness Copilot CLI" -description: "Запуск GitHub Copilot CLI под наблюдением Coven с id harness'а copilot, сессиями в границах проекта и обычными потоками attach и ритуалов." ---- - - -GitHub Copilot CLI — это CLI-агент для кода от GitHub. Coven использует PTY в -границах проекта и для интерактивных, и для one-shot запусков, поэтому -сессии, attach и ритуалы работают так же, как с любым другим harness. - -| Поле | Значение | -|---|---| -| Id harness'а | `copilot` | -| Установка | `npm install -g @github/copilot` или `brew install --cask copilot-cli` | -| Auth | `copilot login` (один раз, на стороне GitHub) | -| Проверка doctor | `coven doctor` сообщает о доступности Copilot CLI и печатает подсказку по установке, если он отсутствует. | - -## Настройка - - - - ```bash - npm install -g @github/copilot - # или - brew install --cask copilot-cli - ``` - - - ```bash - copilot login - ``` - Учётные данные GitHub остаются у Copilot. Coven никогда их не читает. - - - ```bash - coven doctor - ``` - Раздел Harnesses должен содержать `[OK] Copilot CLI` с найденным исполняемым файлом `copilot`. - - - ```bash - coven run copilot "почини падающие тесты" - ``` - - - -## Отображение прав доступа - -Поверхность прав Copilot — это булевы/многотокенные флаги, а не один флаг -режима, поэтому `--permission` в Coven отображается в списки argv: - -| Политика Coven | Argv Copilot | Эффект | -|---|---|---| -| `full` | `--allow-all` | Все инструменты, пути и URL выполняются без подтверждения. | -| `read-only` | `--deny-tool write --deny-tool shell` | Запись файлов и shell-команды запрещаются сразу (правила запрета сильнее любых правил разрешения). Чтение внутри рабочего каталога остаётся доступным. | -| *(нет)* | *(без флагов)* | Действуют настройки Copilot по умолчанию. В неинтерактивном режиме Copilot автоматически отклоняет любой инструмент, который потребовал бы подтверждения. | - -## Непрерывность сессий - -Copilot поддерживает предварительно назначенные id сессий: `coven chat` -отправляет `--session-id ` в первом ходе и тот же флаг в последующих. -`--session-id` создаёт новую сессию под выбранным UUID и возобновляет -существующую, поэтому устаревшие id самовосстанавливаются в новую беседу -вместо ошибки. - -## Устранение неполадок - -| Симптом | Вероятная причина | Решение | -|---|---|---| -| `coven doctor` сообщает, что `copilot` отсутствует | Copilot CLI нет в `PATH` | `npm install -g @github/copilot` (или `brew install --cask copilot-cli`), затем повторите doctor. | -| Запуски сразу падают с ошибкой auth | Нет входа | `copilot login`. | -| `Error: Model "auto" does not support reasoning effort configuration` | `--model auto` вместе с `--think`/`--speed` | Уберите флаг усилия или выберите конкретную модель. | -| Сессия не может прочитать файл вне репозитория | Проверка путей Copilot | Перезапустите с `--add-dir <тот-каталог>`. | - -## См. также - -- [Установка CLI harness'ов](/harnesses/installing) -- [Граница auth провайдера](/harnesses/provider-auth) -- [Руководство по адаптерам harness](/HARNESS-ADAPTERS) diff --git a/docs/ru/harnesses/installing.md b/docs/ru/harnesses/installing.md deleted file mode 100644 index e7f8f4e3..00000000 --- a/docs/ru/harnesses/installing.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -summary: "Как Coven обнаруживает CLI harness'ов и что устанавливать для каждой." -read_when: - - Решение ошибок отсутствующего harness'а - - Настройка новой машины для Coven -title: "Установка CLI harness'ов для Coven" -description: "Как Coven обнаруживает CLI harness'ов в PATH и какие пакеты устанавливать для Codex, Claude Code и других поддерживаемых harness'ов кодирующих агентов." ---- - -Coven **не** содержит CLI harness'ов. Каждый поддерживаемый harness — это независимая CLI, которую Coven обнаруживает в `PATH` во время запуска и контролирует через PTY-адаптер. Эта страница показывает команды установки для каждого harness'а v0 и объясняет, как `coven doctor` сообщает результаты обнаружения. - -## Как работает обнаружение - -И `coven doctor`, и `POST /api/v1/sessions` разрешают id harness'а (`codex`, `claude`, …) в имя исполняемого файла в `PATH`, используя таблицу адаптеров в [Адаптеры harness'ов](/HARNESS-ADAPTERS). Если бинарник отсутствует, Coven отказывается в закрытом виде с подсказкой по установке, а не пытается запустить. - -```mermaid -flowchart LR - Run["coven run codex prompt"] --> Daemon[Coven daemon] - Daemon --> Lookup{harness id known?} - Lookup -- no --> Reject1[Reject: unsupported harness] - Lookup -- yes --> Resolve{executable on PATH?} - Resolve -- no --> Hint["Reject: install hint via coven doctor"] - Resolve -- yes --> Spawn[Spawn validated argv in PTY] -``` - -Демон перепроверяет id harness'а при каждом запросе запуска. Клиенты не могут расширить allowlist, отправив другой argv или путь; принимаются только встроенные id адаптеров. - -## Поддерживаемые harness'ы v0 - -| Id harness'а | Исполняемый файл | Команда установки | Логин провайдера | Страница подробностей | -|---|---|---|---|---| -| `codex` | `codex` | `npm install -g @openai/codex` | `codex login` | [Harness Codex](/harnesses/codex) | -| `claude` | `claude` | `npm install -g @anthropic-ai/claude-code` | `claude doctor` | [Harness Claude Code](/harnesses/claude-code) | -| `copilot` | `copilot` | `npm install -g @github/copilot` | `copilot login` | [Harness Copilot CLI](/harnesses/copilot-cli) | - -Другие CLI (Hermes, Aider, Gemini CLI, Cline, пользовательские команды) **не** входят в v0. См. [Заметки о будущих harness'ах](/FUTURE-HARNESSES) для направления адаптеров. - -## Пошаговая установка - - - - Выбери harness, которым хочешь управлять первым. Можно установить больше позже. - - ```bash - # OpenAI Codex - npm install -g @openai/codex - - # Anthropic Claude Code - npm install -g @anthropic-ai/claude-code - - # GitHub Copilot CLI - npm install -g @github/copilot - ``` - - Другие пути установки (Homebrew, менеджеры пакетов, сборка из исходников) задокументированы в собственном README каждого проекта. Coven требует только, чтобы бинарник был в `PATH` под ожидаемым именем исполняемого файла. - - - - Coven никогда не трогает учётные данные провайдера. Запусти собственный поток логина каждой CLI один раз. - - ```bash - codex login - claude doctor - copilot login - ``` - - См. [Граница auth провайдера](/harnesses/provider-auth) для обоснования. - - - - ```bash - coven doctor - ``` - - Ожидаемый вывод (сокращённый): - - ```text - store: ok - project: ok (/path/to/project) - daemon: running (pid 12345) - codex: ok (/usr/local/bin/codex 0.x.y) - claude: ok (/usr/local/bin/claude 0.x.y) - ``` - - Если строка показывает `missing`, doctor также печатает точную команду установки, показанную в таблице выше. - - - - ```bash - coven run codex "describe this repo" - coven run claude "polish the CLI help text" - ``` - - - -## Обновление harness'а - -Coven не авто-обновляет CLI harness'ов. Рассматривай их как обычные глобальные npm-установки (или другого менеджера пакетов): - -```bash -npm install -g @openai/codex@latest -npm install -g @anthropic-ai/claude-code@latest -npm install -g @github/copilot@latest -``` - -После обновления повторно запусти `coven doctor`, чтобы подтвердить, что разрешённый путь/версия по-прежнему соответствует ожидаемому. - -## Пользовательские расположения исполняемых файлов - -Если harness установлен в каталоге вне `PATH` (например, локальный для проекта `node_modules/.bin`), убедись, что этот каталог в `PATH` **до** запуска демона. Coven уважает окружение процесса демона, а не окружение вызывающего shell, при запуске PTY. - -Если ты меняешь `PATH` системно, перезапусти демон: - -```bash -coven daemon restart -coven doctor -``` - -## Решение проблем - -| Симптом | Вероятная причина | Решение | -|---|---|---| -| `coven doctor` сообщает harness как `missing` даже после установки | Новый `PATH` shell'а не подхвачен демоном | `coven daemon restart`, затем `coven doctor`. | -| Doctor находит бинарник, но `coven run` падает немедленно | Auth провайдера не завершён | Перезапусти `codex login` / `claude doctor`. См. [auth провайдера](/harnesses/provider-auth). | -| Doctor показывает устаревшую версию | Старый бинарник раньше в `PATH` | `which -a codex` (или `claude`) и удали дубликат. | -| Doctor сообщает `unsupported harness` | Опечатка в id harness'а | Используй один из id из таблицы выше. | - - -## Связанное - -- [Harness'ы](/harnesses/index) -- [Harness Codex](/harnesses/codex) -- [Harness Claude Code](/harnesses/claude-code) -- [Адаптеры harness'ов](/HARNESS-ADAPTERS) -- [Заметки о будущих harness'ах](/FUTURE-HARNESSES) diff --git a/docs/ru/harnesses/provider-auth.md b/docs/ru/harnesses/provider-auth.md deleted file mode 100644 index 0390e103..00000000 --- a/docs/ru/harnesses/provider-auth.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -summary: "Coven не хранит учётные данные провайдера. Каждый harness продолжает использовать свой собственный логин." -read_when: - - Аудит, где живут учётные данные - - Решение, что Coven разрешено читать или проксировать - - Обзор границы безопасности перед развёртыванием Coven на общей машине -title: "Граница auth провайдера harness'а" -description: "Coven не хранит и не проксирует учётные данные провайдера: каждый harness сам логинится в OpenAI, Anthropic или другом провайдере через свой собственный поток." ---- - -Coven контролирует PTY harness'ов. Он никогда не читает, не проксирует, не сохраняет и не выпускает учётные данные провайдера. Каждый поддерживаемый harness продолжает использовать **свой собственный** поток логина для OpenAI, Anthropic или любого будущего провайдера, с которым он говорит. Эта страница фиксирует, почему, что это означает на практике, и точную границу, которую применяет демон на Rust. - -## TL;DR - -- Токены провайдера живут там, где harness уже их кладёт — обычно `~/.codex/`, `~/.config/anthropic/` или системный keychain, управляемый этой CLI. -- Демон Coven никогда их не читает, никогда не хранит в SQLite, никогда не пересылает через socket API и никогда не логирует в журнал событий. -- `coven doctor` только проверяет, существует ли бинарник harness'а; он **не** тестирует учётные данные провайдера. Каждый harness уже поставляет собственный `login` / `doctor` для этого. -- Рассматривай Coven как имеющий **нулевое** знание о состоянии auth провайдера. Граница намеренная. - -## Почему Coven отказывается владеть учётными данными - -```mermaid -flowchart LR - User[Developer] -->|once| HarnessLogin["harness login (codex login / claude doctor)"] - HarnessLogin --> HarnessStore[("Provider credential store\n~/.codex, keychain, etc.")] - - User -->|every run| CovenRun["coven run codex prompt"] - CovenRun --> Daemon[Coven daemon] - Daemon -.->|never reads| HarnessStore - Daemon --> PTY[Harness PTY] - PTY --> HarnessStore - PTY --> Provider[Provider API] -``` - -Стрелка, которая имеет значение, — это отсутствующая: у демона нет пунктирной линии в хранилище учётных данных провайдера. Три причины: - -1. **Меньший радиус взрыва.** Скомпрометированный демон, socket или клиент Coven не может слить токены провайдера, которых у него никогда не было. Баг в логировании событий не может случайно записать токен, которым Coven никогда не владел. -2. **Без drift учётных данных.** Codex, Claude Code и будущие harness'ы итерируют свои собственные потоки auth (OAuth refresh, device codes, on-device keys). Coven должен был бы гоняться за каждым изменением. Оставаясь в стороне, мы никогда не выходим из синхронизации. -3. **Ясность аудита.** Когда что-то идёт не так с биллингом, лимитами или отозванными токенами, пользователь знает, что ответ живёт в **одном** месте — собственной CLI harness'а. Coven — это не слой учётных данных для дебагинга. - -## Что это означает на каждой поверхности - -### CLI - -`coven run codex|claude ` запускает harness с пустым вектором аргументов, кроме валидированного prompt и prefix args адаптера. Он не инъецирует `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` или любую env var, несущую токен. Если harness нуждается в учётных данных, он читает их так же, как при запуске напрямую из твоего shell. - -### API демона - -`POST /api/v1/sessions` принимает корень проекта, cwd, id harness'а, prompt и опциональный заголовок. Нет поля для API-ключа, OAuth-токена, refresh-токена, id учётной записи или id организации. Схема задокументирована в [Контракт API](/API-CONTRACT) — ни одного из этих полей не существует. - -### Журнал событий - -Append-only журнал событий записывает stdout/stderr harness'а по мере его выдачи. Демон не интроспектирует и не редактирует его; это значит, что если **ты** просишь harness напечатать `cat ~/.codex/auth.json`, вывод **попадёт** в журнал. См. [Модель безопасности](/SAFETY-MODEL#event-log-caution) для руководства со стороны пользователя. - -### Клиентские интеграции - -Клиенты (comux, клиент чата/ввода, плагин OpenClaw) подключаются к локальному socket. Они не могут получить токены провайдера от демона, потому что у демона их нет. Любой клиент, который хочет показать "logged in as ...", должен вызывать собственную команду статуса harness'а напрямую. - -## Логин провайдера на harness - -| Harness | Команда логина | Где живут учётные данные | Заметки | -|---|---|---|---| -| `codex` | `codex login` | `~/.codex/auth.json` (или платформенный keychain, в зависимости от версии Codex) | Используй `codex logout`, чтобы отозвать. Coven не нужно перезапускать. | -| `claude` | `claude doctor`, затем следуй подсказкам | `~/.config/anthropic/` и/или системный keychain | `claude doctor` также является общей проверкой здоровья; Coven полагается только на наличие бинарника. | -| `copilot` | `copilot login` | `~/.copilot/` (токен device-flow GitHub, управляемый самой CLI) | Используй `copilot logout`, чтобы отозвать. Доступ к Copilot на стороне GitHub определяется твоим планом GitHub. | - -Если поток `login` самого harness'а имеет проблему (истёкший refresh-токен, отозванная org, сетевой сбой), Coven отображает это как нормальный выход harness'а — сессия заканчивается с тем кодом выхода, который вернула CLI, а журнал событий содержит сообщение об ошибке, напечатанное CLI. - -## Что применяет Coven - -Ответственность демона — **оставаться вне пути учётных данных**. Конкретно: - -- Демон не читает переменные окружения, которые выглядят как учётные данные провайдера, перед запуском harness'а. -- Демон не инъецирует env vars провайдера в PTY-child за пределами того, что унаследовал сам процесс демона при запуске. -- CLI не принимает флаг `--token`, `--api-key`, `--openai-key` или подобный в `coven run`. Если ты видишь такой в форке или PR, это регрессия — пожалуйста, открой issue. -- Socket API не принимает поля учётных данных. Неизвестные поля игнорируются; явные поля учётных данных были бы отвергнуты и рассматривались как нарушение контракта. - -## Что должен делать пользователь - -Поскольку Coven отказывается владеть учётными данными, **пользователь** ответственен за: - -- Запуск собственного потока `login` / `doctor` каждого harness'а хотя бы раз перед ожиданием, что `coven run` будет успешен. -- Ротацию токенов провайдера через CLI harness'а при необходимости. -- Обращение с любым выводом harness'а, который печатает учётные данные (потому что ты попросил), как с записанным в журнал — очисти его с помощью [`coven sacrifice`](/SESSION-LIFECYCLE#sacrifice) при необходимости. - - -## Связанное - -- [Аутентификация и локальный доступ](/AUTH) -- [Модель безопасности](/SAFETY-MODEL) -- [Установка CLI harness'ов](/harnesses/installing) -- [Адаптеры harness'ов](/HARNESS-ADAPTERS) -- [Harness Codex](/harnesses/codex) -- [Harness Claude Code](/harnesses/claude-code) diff --git a/docs/ru/index.md b/docs/ru/index.md deleted file mode 100644 index 0b1872c8..00000000 --- a/docs/ru/index.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -summary: "Coven — это local-first runtime-подложка для постоянных AI-фамильяров. Один демон управляет каждым harness кодирующего агента с сессиями в границах проекта, append-only событиями и типизированным локальным socket API." -read_when: - - Знакомство OpenCoven и Coven с новичками - - Решение, устанавливать ли Coven для локальной работы с агентами -title: "Coven" -description: "Coven — это local-first runtime, который управляет CLI кодирующих агентов в сессиях, ограниченных проектом, с append-only событиями и локальным socket API." ---- - - -
- OpenCoven -
-

Приведи любого фамильяра в круг.

-

OpenCoven — это открытая экосистема для постоянных AI-фамильяров. Coven — это локальная runtime-подложка, которая управляет каждым harness — Codex, Claude Code и будущими Hermes, Aider и Gemini CLI — внутри явных границ проекта.

-

Запусти сессию, наблюдай за PTY, подключайся позже, архивируй по завершении. Один демон, один socket, все фамильяры в равных условиях.

-
-
- - - - Установи Coven, запусти `coven doctor` и запусти harness-сессию в границах проекта. - - - Демон, надзор за PTY, валидация корня проекта, сессии, события и авторитет локального socket. - - - Текущие команды `coven`: run, sessions, attach, daemon, doctor, archive, summon и sacrifice. - - - -## Что такое Coven? - -Coven — это **local-first runtime-подложка**: единственный демон на Rust, который владеет PTY harness'ов, состоянием сессий и append-only журналом событий на твоей собственной машине. Клиенты вроде CLI/TUI `coven`, кокпит comux, клиент чата/ввода и внешний OpenClaw-плагин все координируются через один версионированный контракт HTTP-поверх-Unix-socket. - -**Для кого это?** Разработчики и операторы, которые хотят, чтобы их AI-фамильяры продолжали работать локально, помнили, что они делали, и оставались внутри границ проекта, которые можно проаудитить. - -**Что делает его другим сегодня?** - -- **Local-first** — демон, хранилище и socket живут под `$COVEN_HOME`. Без облачного релея, без OAuth демона. -- **Нейтрален к harness'у** — Codex и Claude Code сегодня, с задокументированной планкой адаптера для будущих harness'ов. Тот же жизненный цикл, те же ритуалы. -- **С привязкой к проекту** — каждый запуск несёт явный корень проекта и канонизированный рабочий каталог. Демон на Rust перепроверяет каждый запрос. -- **Инспектируемый** — сессии и события — это строки SQLite, которые можно просмотреть с помощью `coven sessions`, воспроизвести с `coven attach` или принести в жертву, когда они больше не нужны. -- **Лицензия MIT** — упакован для ранних пользователей под `@opencoven/*`, команда всегда `coven`. - -**Что тебе нужно?** Стабильный toolchain Rust (или опубликованный wrapper `@opencoven/cli`), хотя бы одна поддерживаемая CLI harness'а в `PATH` и проект, в котором запускаться. - -## Как это работает - -```mermaid -flowchart LR - A["coven CLI / TUI"] --> B["Coven daemon"] - C["comux cockpit"] --> B - D["chat/intent client"] --> B - E["OpenClaw bridge plugin"] --> B - B --> F["Codex PTY"] - B --> G["Claude Code PTY"] - B --> H["Future harness PTYs"] - B --> I[("SQLite session ledger")] - B --> J[("Append-only event log")] -``` - -Демон — единственный источник истины для сессий, жизненного цикла PTY и маршрутизации capabilities. - -## Ключевые возможности - - - - Codex и Claude Code запускаются через один контролируемый слой PTY. - - - Каждая сессия фиксирует канонический корень проекта и отказывается отходить от него. - - - Воспроизводи вывод, восстанавливайся после перезапусков демона и проверяй, что harness реально делал. - - - Archive, summon и sacrifice — явные, безопасные для новичков глаголы вокруг разрушительных операций. - - - Сначала `GET /api/v1/health`; затем sessions, events, capabilities и actions через Unix socket. - - - comux, клиент чата/ввода и мост OpenClaw интегрируются как socket-клиенты, а не как авторитеты запуска. - - - -## Быстрый старт - - - - ```bash - npm install -g @opencoven/cli - ``` - Собираешь из исходников? См. [Начать](/GETTING-STARTED). - - - ```bash - coven doctor - ``` - `doctor` сообщает, есть ли `codex` и `claude` в `PATH`, может ли socket демона привязаться и что устанавливать дальше. - - - ```bash - coven daemon start - coven daemon status - ``` - - - ```bash - cd /path/to/your/project - coven run codex "describe this repo" - ``` - Или открой удобный для людей браузер сессий: - - ```bash - coven sessions - ``` - - - -Нужны полные инструкции по установке и настройке для разработчиков? См. [Начать](/GETTING-STARTED). - -## Браузер сессий - -`coven sessions` открывает удобный для людей браузер каждой живой и архивной сессии. Выбери одну, затем выбери ритуал: - -- **Rejoin** — подключись к живому PTY и следи за его выводом. -- **View log** — открой append-only журнал событий. -- **Summon** — восстанови архивную сессию в активном списке. -- **Archive** — скрой завершённую сессию без удаления событий. -- **Sacrifice** — навсегда удали не выполняющуюся сессию (требует `--yes`). - -Существуют также варианты, дружественные к pipe: `coven sessions --plain` для таблиц, `coven sessions --json` для клиентов. - -## Конфигурация (опционально) - -Состояние Coven живёт под `$COVEN_HOME` (по умолчанию `~/.coven` на macOS/Linux). Демон привязывает Unix socket по адресу `/coven.sock` и по умолчанию отказывается от TCP. - -- Если ты **ничего не делаешь**, Coven использует твои существующие локальные логины harness'ов. -- Если хочешь ограничить это, ограничь `$COVEN_HOME` на каждый корень проекта или каждого фамильяра. - -Пример: - -```bash -export COVEN_HOME="$HOME/.local/share/coven" -coven daemon restart -``` - -## Начни здесь - - - - Топология runtime, граница авторитета, жизненный цикл сессии и плоскость управления. - - - Настройка по каждому harness, граница auth провайдера и ожидания адаптера. - - - Версионированный socket API для comux, клиента чата/ввода, OpenClaw-плагина и твоих собственных клиентов. - - - Archive, summon и sacrifice — безопасные для новичков глаголы вокруг состояния сессии. - - - Распространённые проблемы установки, переменные окружения и как подать пакет диагностики. - - - -## Узнать больше - - - - Граница авторитета, гарантии хранилища, поддерживаемые harness'ы и сигналы roadmap. - - - Граница доверия, обращение с секретами, поза socket и одобрения автоматизации. - - - Диагностика демона, подсказки по установке harness'ов, восстановление осиротевших сессий и проверка. - - - Текущие milestones, направление адаптеров и публичные границы продукта. - - diff --git a/docs/ru/install/windows.md b/docs/ru/install/windows.md deleted file mode 100644 index a316e0bb..00000000 --- a/docs/ru/install/windows.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -summary: "Установка Coven на нативный Windows." -read_when: - - Установка на Windows -title: "Установка на Windows" -description: "Установка Coven на Windows: как настроить wrapper, нативный бинарник демона, COVEN_HOME и CLI харнессов на хосте Windows или в среде WSL2." ---- - -# Установка на Windows - -Используй опубликованный npm-wrapper из PowerShell, Windows Terminal или другого терминала, который может запускать пакеты Node.js: - -```powershell -npx @opencoven/cli doctor -``` - -Для регулярного использования установи wrapper глобально: - -```powershell -npm install -g @opencoven/cli -coven doctor -``` - -Wrapper предоставляет команду `coven` и запускает нативный Windows-бинарник, если пакет релиза содержит его для твоей платформы. `coven doctor` — это первый шаг проверки: он анализирует локальное состояние и сообщает, доступны ли в `PATH` поддерживаемые CLI харнессов, такие как Codex или Claude Code. - -## Первый запуск - -Из каталога проекта: - -```powershell -coven -``` - -Команда по умолчанию открывает prompt-first TUI. Также можно использовать явный поток CLI: - -```powershell -coven doctor -coven daemon start -coven run codex "fix the failing tests" -coven sessions -``` - -Установи и авторизуй хотя бы одну CLI харнесса, прежде чем ожидать, что `coven run` запустит работу. Если `coven doctor` сообщает об отсутствующем харнессе, установи этот инструмент, открой новый терминал, чтобы `PATH` обновился, и снова запусти `coven doctor`. - -## Заметки по Windows - -- При переопределении `COVEN_HOME` храни его по локальному пути, принадлежащему твоему пользователю Windows. -- Запускай Coven и CLI харнесса из одного и того же окружения. Харнесс, установленный только внутри WSL2, недоступен для нативного PowerShell Windows, если ты не предоставишь его отдельно. -- Если ввод в терминале ведёт себя странно, обнови wrapper до последней версии и снова запусти `coven tui`. TUI на Windows фильтрует события нажатия клавиш, так что набранные символы, стрелки и Enter должны обрабатываться один раз. - -## Связанное - -- [Начало работы с Coven](/GETTING-STARTED) -- [TUI Coven](/start/coven-tui) -- [Устранение неполадок](/TROUBLESHOOTING) -- [Справочник CLI](/reference/cli) diff --git a/docs/ru/reference/api.md b/docs/ru/reference/api.md deleted file mode 100644 index d154bcaf..00000000 --- a/docs/ru/reference/api.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -summary: "Текущие endpoint'ы локального socket API Coven." -read_when: - - Поиск endpoint'а - - Построение клиента против `/api/v1` -title: "Справочник API Coven" -description: "Справочник endpoint'ов для локального socket API Coven под /api/v1: health, capabilities, actions, sessions, events и пересылка input." ---- - - -Демон Coven предоставляет свой публичный API как HTTP через Unix socket под `/coven.sock`. Активный контракт — **`coven.daemon.v1`**, обслуживаемый под `/api/v1`. - -```mermaid -flowchart LR - Root["/api/v1"] --> Version["GET /api-version"] - Root --> Health["GET /health"] - Root --> Capabilities["GET /capabilities"] - Root --> Actions["POST /actions"] - Root --> Sessions["/sessions"] - Root --> Events["GET /events"] - - Sessions --> SList["GET /"] - Sessions --> SCreate["POST /"] - Sessions --> SById["/:id"] - SById --> SGet["GET /"] - SById --> SInput["POST /input"] - SById --> SKill["POST /kill"] -``` - -## Endpoint'ы - -| Метод | Путь | Назначение | Тело | Успех | Ошибки | -|---|---|---|---|---|---| -| GET | `/api/v1/api-version` | Активная версия API + поддерживаемые версии. | — | `{ apiVersion, supportedApiVersions }` | — | -| GET | `/api/v1/health` | Доступность демона, версия, capabilities, pid. | — | `{ ok, apiVersion, covenVersion, capabilities, daemon }` | `503 runtime_unavailable` | -| GET | `/api/v1/capabilities` | Каталог capabilities с подсказками политики. | — | `{ capabilities: [...] }` | — | -| GET | `/api/v1/capabilities/harnesses` | Агрегат манифестов capabilities harness'ов плюс skills Coven (`?refresh=1` пересканирует). | — | `{ coven_skills, harness_capabilities, scanned_at }` | — | -| GET | `/api/v1/capabilities/:harness` | Манифест capabilities одного harness'а (`?refresh=1` пересканирует). | — | объект манифеста | `404 harness_not_found` | -| POST | `/api/v1/actions` | Маршрутизировать известный id действия плоскости управления. | `{ action, origin, intentId, args }` | `{ ok, accepted, status, event }` | `400 invalid_request` (неизвестное действие) | -| GET | `/api/v1/sessions` | Перечислить активные сессии. | — | `SessionRecord[]` | — | -| POST | `/api/v1/sessions` | Запустить сессию harness'а, ограниченную проектом. | `{ projectRoot, cwd?, harness, prompt, title?, launchMode?, conversation?, conversationId? }` | `SessionRecord` | `400 invalid_request` (включая cwd вне проекта, неизвестный id harness, некорректный body), `500 launch_failed` (runtime spawn / начальная запись / старт CLI дали сбой; строка помечена как `failed`) | -| GET | `/api/v1/sessions/:id` | Получить одну сессию. | — | `SessionRecord` | `404 session_not_found` | -| POST | `/api/v1/sessions/:id/input` | Переслать input в живую сессию. | `{ data }` | `{ ok, accepted }` | `400 invalid_request` (некорректный body / `data` отсутствует или не-string), `404 session_not_found`, `409 session_not_live`, `500 send_input_failed` | -| POST | `/api/v1/sessions/:id/kill` | Убить живую сессию. | — | `{ ok, accepted }` | `404 session_not_found`, `409 session_not_live`, `500 kill_failed` | -| GET | `/api/v1/events` | Прочитать пагинированные события сессии. | — (`?sessionId`, `?afterSeq`, `?afterEventId`, `?limit`) | `{ events, nextCursor, hasMore }` | `400 invalid_request` | - -Все ответы об ошибках используют структурированный конверт, задокументированный в [Контракт API](/API-CONTRACT#structured-error-envelope). - -## Всегда начинай с health - -```http -GET /api/v1/health -``` - -Ответ говорит тебе активную `apiVersion`, `capabilities` демона и работающий pid/uptime. Рассматривай остальную часть API как неопределённую, пока не прочитаешь эти поля. - -См. [Локальный API Coven](/API) для примеров ответов и [Контракт API](/API-CONTRACT) для стабильных форм и конвертов сбоев. - -## Связанное - -- [Локальный API Coven](/API) -- [Контракт API](/API-CONTRACT) -- [Аутентификация и локальный доступ](/AUTH) -- [Интеграция клиентов](/CLIENT-INTEGRATION) diff --git a/docs/ru/reference/cli.md b/docs/ru/reference/cli.md deleted file mode 100644 index 15290728..00000000 --- a/docs/ru/reference/cli.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -summary: "Текущая поверхность команд CLI Coven." -read_when: - - Поиск флага CLI Coven - - Скриптинг против CLI Coven -title: "Справочник CLI Coven" -description: "Справочник команд CLI coven: doctor, daemon, run, sessions, attach, archive, kill, summon, sacrifice и view, плюс флаги TUI и команд автоматизации." ---- - - -Команда, ориентированная на пользователя, — это всегда `coven`. Wrapper-пакеты, такие как `@opencoven/cli`, `@opencoven/cli-macos` и `@opencoven/cli-linux-x64`, устанавливают один и тот же бинарник. - -```mermaid -flowchart TB - Root["coven"] --> TUI["tui (default)"] - Root --> Doctor["doctor"] - Root --> Daemon["daemon"] - Root --> Run["run"] - Root --> Sessions["sessions"] - Root --> Attach["attach"] - Root --> Summon["summon"] - Root --> Archive["archive"] - Root --> Sacrifice["sacrifice"] - Root --> Patch["patch"] - Root --> Pc["pc (macOS-first)"] - - Daemon --> DStart["start"] - Daemon --> DStatus["status"] - Daemon --> DRestart["restart"] - Daemon --> DStop["stop"] - - Run --> RCodex["codex <prompt>"] - Run --> RClaude["claude <prompt>"] - - Sessions --> SPlain["--plain"] - Sessions --> SJson["--json"] - Sessions --> SAll["--all"] - Sessions --> SManage["--manage"] - - Patch --> POpenclaw["openclaw <prompt>"] - - Pc --> PcStatus["status [--json]"] - Pc --> PcTop["top --n N"] - Pc --> PcDisk["disk"] - Pc --> PcKill["kill <pid> --confirm"] - Pc --> PcCache["cache clear --confirm"] -``` - -## Верхний уровень - -| Команда | Действие | -|---|---| -| `coven` | Открывает удобное для новичков интерактивное меню. | -| `coven tui` | Явно открывает TUI slash-команд. | -| `coven doctor` | Обнаруживает поддерживаемые CLI harness'ов и печатает подсказки по установке. | -| `coven daemon start/status/restart/stop` | Управляет локальным демоном. | -| `coven run ` | Запускает сессию harness'а, ограниченную проектом. Текущие id harness'ов: `codex`, `claude`. | -| `coven sessions` | Открывает браузер сессий; поддерживает `--plain`, `--json`, `--all` и `--manage`. | -| `coven attach ` | Воспроизводит/следит за выводом сессии и пересылает input, когда жива. | -| `coven summon ` | Восстанавливает архивную сессию, затем воспроизводит/следит за ней. | -| `coven archive ` | Скрывает не выполняющуюся сессию, сохраняя события. | -| `coven sacrifice --yes` | Навсегда удаляет не выполняющуюся сессию. | -| `coven patch openclaw ` | Локальный цикл спасения OpenClaw. Не делает commit или push. | -| `coven pc` | macOS-first диагностика и операции облегчения с явным `--confirm`. | - -## Общие флаги по команде - -| Команда | Флаги | -|---|---| -| `coven run` | `--cwd `, `--title `, `--json`, `--detach` | -| `coven sessions` | `--plain`, `--json`, `--all`, `--manage` | -| `coven attach` | `--follow` (по умолчанию), `--no-follow` (только replay) | -| `coven sacrifice` | `--yes` (обязательный) | -| `coven daemon start` | `--coven-home ` (переопределяет `$COVEN_HOME`) | -| `coven pc kill` | `--confirm` (обязательный) | -| `coven pc cache clear` | `--confirm` (обязательный) | -| `coven pc top` | `--n `, `--verbose` | -| `coven pc status` | `--json` | - -## Соглашения по флагам - -- **Команды, ограниченные проектом** принимают `--cwd ` для каталога запуска внутри корня проекта. -- **Команды, дружественные к pipe** принимают `--plain` для таблиц и `--json` для машинного вывода. -- **Разрушительные команды** требуют `--yes` (или `--confirm` для облегчения `coven pc`). -- **Команды, затрагивающие демон** печатают подсказки по установке/восстановлению, когда socket отсутствует. - -## Коды выхода - -| Код | Значение | -|---|---| -| `0` | Успех. | -| `1` | Общая ошибка CLI (плохой argv, неизвестная подкоманда). | -| `2` | Ошибка валидации (cwd вне корня, неизвестный id harness'а). | -| `3` | Демон недоступен (socket отсутствует или нездоров). | -| `4` | Разрушительное действие отвергнуто (отсутствует `--yes` / `--confirm`, или цель жива). | -| `>=10` | Зарезервировано для будущих структурированных кодов выхода; текущие сборки могут их ещё не выдавать. | - -Команда `coven attach` выходит с кодом выхода базовой сессии, когда сессия больше не жива, поэтому скрипты могут пайпить `coven run … && coven attach ` и наблюдать собственный статус harness'а. - -## Связанное - -- [Начать](/GETTING-STARTED) -- [TUI Coven](/start/coven-tui) -- [Жизненный цикл сессии](/SESSION-LIFECYCLE) -- [Руководство по адаптерам harness'ов](/HARNESS-ADAPTERS) -- [Решение проблем](/TROUBLESHOOTING) diff --git a/docs/ru/reference/release-notes.md b/docs/ru/reference/release-notes.md deleted file mode 100644 index 64ee2e00..00000000 --- a/docs/ru/reference/release-notes.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -summary: "Заметки о выпусках среды выполнения, CLI и локального API Coven." -description: "Еженедельные release notes Coven с новыми возможностями, исправлениями и несовместимыми изменениями среды выполнения, CLI, TUI и локального socket API." -read_when: - - Looking up what changed -title: "Changelog и release notes Coven" ---- - -## Неделя от 14 июля 2026 - -### Новые возможности - -- **GitHub Copilot CLI — поддерживаемый встроенный harness (v0.0.54).** `coven run copilot "…"` теперь запускает GitHub Copilot CLI (`npm install -g @github/copilot`) под тем же PTY-наблюдением в границах проекта, что Codex и Claude Code. `--permission full|read-only` отображается в нативные флаги Copilot (`--allow-all` / `--deny-tool write --deny-tool shell`), `--model`, `--add-dir` и `--think`/`--speed` (через `--effort`) пробрасываются нативно, а `coven chat` сохраняет беседы между ходами через предварительно назначенные UUID `--session-id`. См. [Harness Copilot CLI](/harnesses/copilot-cli) и [issue #381](https://github.com/OpenCoven/coven/issues/381). - -## Неделя от 4 июля 2026 - -### Обновления - -- **Выбор модели только через login CLI (v0.0.53).** Документация выбора модели теперь показывает только поддерживаемые пути Codex CLI и Claude Code. Провайдерские/API-key страницы для OpenAI, Anthropic, Google и локальных model backend'ов убраны из выбираемой поверхности `/models`, чтобы клиенты и пользователи шли через `codex login` или `claude doctor`, а не через сырые учётные данные провайдера. См. [Model selection](/models). - -## Неделя от 24 июня 2026 - -### Новые возможности - -- **Сопубликованный npm-обёртка external OpenClaw bridge plugin (v0.0.49).** Release-pipeline теперь публикует второе имя обёртки, external OpenClaw bridge plugin, рядом с существующим `@opencoven/cli`. Обе обёртки зависят от одних и тех же native-пакетов `@opencoven/cli-*`, поэтому установка любой из них даёт тот же бинарь `coven`. Это позволяет docs и онбордингу рекламировать каноническое имя *coven*, не ломая существующие установки `@opencoven/cli`. См. [PR #257](https://github.com/OpenCoven/coven/pull/257) и [руководство по релизам](/reference/releasing) для одноразовой настройки Trusted Publisher, которая нужна для первого OIDC-релиза нового пакета. -- **Spec Coven Group Chat (v0.0.49).** Добавлен v1-дизайн серверной примитивы группового чата в `specs/coven-group-chat/` (PRODUCT + TECH). Сегодня групповой чат существует только как клиентская fan-out-иллюзия в iOS; spec определяет долговременный серверный объект с монотонной нумерацией событий, чтобы iOS, web и CLI видели одну и ту же группу. Реализация отслеживается отдельно. См. [PR #258](https://github.com/OpenCoven/coven/pull/258). - -### Обновления - -- **Убраны упоминания OpenMeow в docs и коде (v0.0.49).** OpenMeow не является приложением OpenCoven — канонический клиент это CastCodes. Оставшиеся примеры и метки OpenMeow в английских/испанских/русских docs, в `DESIGN.md`, `ARCHITECTURE.md`, `AUTH.md`, `API-CONTRACT.md` и смежных файлах переписаны нейтрально по отношению к продукту. `crates/coven-cli/src/api.rs` переименовывает тестовое origin `openmeow` в `external-client`, а `skills/coven-task-manager` убирает `openmeow` из списка распознаваемых меток репозиториев. Изменений в runtime-поведении нет. См. [PR #256](https://github.com/OpenCoven/coven/pull/256). - -## Неделя от 18 июня 2026 - -### Новые возможности - -- **Управление reasoning для `coven run` (v0.0.48).** `coven run` теперь принимает `--think` и `--speed fast|balanced|thorough` вместе с `--model`. Запуски Claude преобразуют эти подсказки в `--effort`; неподдерживаемые harnesses предупреждают и продолжают работу вместо аварийного завершения. См. [issue #246](https://github.com/OpenCoven/coven/issues/246), [PR #254](https://github.com/OpenCoven/coven/pull/254) и [справочник `coven run`](/reference/cli-run). -- **Доверенный рецепт адаптера Hermes (v0.0.41).** `coven adapter install hermes` теперь записывает доверенный локальный manifest в `COVEN_HOME/adapters/hermes.json`, а Coven автоматически загружает manifests из собственного trust store. Новым пользователям больше не нужно вручную писать JSON или задавать `COVEN_HARNESS_ADAPTER_MANIFEST`, чтобы попробовать Hermes. - -### Обновления - -- **Статус пакета Windows x64.** Публичный README теперь отражает, что `@opencoven/cli-windows` опубликован, а не находится в staging. Пользователи Windows могут установить универсальный wrapper `@opencoven/cli` и проверить локальные harnesses через `coven doctor`. - -### Исправления ошибок - -- **Устойчивый backfill FTS-индекса событий (v0.0.48).** Backfill существующих событий в `events_fts` теперь выполняется ограниченными batch-ами, записывает завершение в `store_meta`, применяет `busy_timeout` к read-only соединениям и считает `SQLITE_BUSY` нефатальным, чтобы поисковая индексация не блокировала все запуски агентов на больших историях. См. [issue #249](https://github.com/OpenCoven/coven/issues/249) и [PR #254](https://github.com/OpenCoven/coven/pull/254). -- **Более понятная подсказка для неподдерживаемых harnesses.** Ошибки неизвестного harness теперь показывают настроенные IDs и направляют пользователей Hermes к `coven adapter install hermes`, затем к `coven adapter doctor hermes`. -- **Fallback домашнего каталога на Windows.** `coven doctor` и выбор store path работают в PowerShell без `HOME`, последовательно проверяя `USERPROFILE`, `HOMEDRIVE` + `HOMEPATH` и системный home перед тем, как попросить задать `COVEN_HOME`. - -## Неделя от 3 июня 2026 - -### Новые возможности - -- **Протокол параллельной работы Coven.** В Coven появились команды `coven wt`, `coven claim` и `coven hooks` для координации нескольких AI-агентов разработки в одном репозитории. Протокол создаёт изолированные git worktree, записывает claims на ветки с TTL, устанавливает цепочечные safety hooks, блокирует случайные коммиты в защищённые ветки и требует явную фразу намерения merge перед push в защищённые ветки. См. [issue #167](https://github.com/OpenCoven/coven/issues/167) и [PR #169](https://github.com/OpenCoven/coven/pull/169). -- **Сохранение идентичности familiar в сессиях.** Сессии теперь могут хранить разрешённый `familiar_id`, чтобы dashboards, API и агентские поверхности могли стабильно показывать, какой familiar запустил сессию или владеет ей. См. [PR #168](https://github.com/OpenCoven/coven/pull/168). - -### Обновления - -- **Общая резолюция familiars.** CLI, daemon и локальный API теперь разрешают familiar identities через один общий путь перед запуском, поэтому сохранённые метаданные сессии отражают каноническую familiar identity, а не непроверенную входную строку. -- **Guardrails для параллельных lane.** Протокол worktree включает поверхности status, doctor, prune, claim acquire/release/heartbeat/canary и установку hooks, чтобы координация агентов масштабировалась без ad hoc shell-скриптов. - -### Исправления ошибок - -- **Неизвестные familiar IDs больше не создают сессии.** `POST /sessions` теперь отклоняет неизвестный `familiarId` с `400 unknown_familiar` до вставки строки сессии или запуска runtime. Некорректная конфигурация familiars возвращает `500 familiar_lookup_failed` без запуска. -- **`coven run --familiar ` рано завершается для неизвестных familiars.** Локальные CLI-запуски теперь соответствуют поведению daemon/API и не сохраняют неразрешённые familiar IDs. - -## Неделя от 17 мая 2026 - -### Исправления ошибок - -- **Больше никаких двойных нажатий в TUI на Windows.** `coven tui` и браузер сессий теперь фильтруют только события нажатия клавиш в Windows, поэтому при наборе `a` больше не вставляется `aa`, стрелки переходят на одну строку за нажатие, а Enter активирует выбор один раз. На macOS и Linux поведение не меняется. См. [Coven TUI](/start/coven-tui) и [Установка в Windows](/install/windows). -- **TUI больше не падает на маленьких терминалах.** И `coven tui`, и `coven chat` теперь защищают свои расчёты разметки от очень маленьких размеров терминала, поэтому изменение размера окна на узкое или низкое больше не приводит к аварийному завершению сессии. См. [Coven TUI](/start/coven-tui). -- **Гигиена release gate.** Guard секретов публичного релиза теперь разрешает публичные URL GitHub advisories и сканирует историю релиза от `HEAD`, чтобы устаревшие удалённые ветки не блокировали текущий gate. - -### Безопасность - -- **Уведомление безопасности Ratatui устранено.** Обновлён рендеринг-стек Ratatui, чтобы подтянуть пропатченный crate `lru`, что устраняет уведомление [GHSA-rhfx-m35p-ff5j](https://github.com/advisories/GHSA-rhfx-m35p-ff5j). Никаких действий не требуется — просто установите последнюю версию. - -## Неделя от 15 мая 2026 - -### Обновления - -- **Тема TUI в фирменном стиле.** И `coven tui`, и `coven chat` теперь используют единую палитру в фирменном стиле с согласованными семантическими токенами для стилей primary, agent, user, hint, surface и dim. Цвета автоматически адаптируются к вашему терминалу: truecolor в 24-битных терминалах, 256-цветный режим в устаревших терминалах и без цвета, когда вывод перенаправлен или установлен `NO_COLOR`. См. [Troubleshooting](/TROUBLESHOOTING). - -## Как читать этот changelog - -```mermaid -flowchart LR - Week["Еженедельная запись\n(YYYY-MM-DD)"] --> New["### Новые возможности"] - Week --> Upd["### Обновления"] - Week --> Fix["### Исправления ошибок"] - Week --> Sec["### Безопасность (когда применимо)"] - - New --> Links["Каждый пункт ссылается на канонический документ или PR"] - Upd --> Links - Fix --> Links - Sec --> Links -``` - -Записи еженедельные, новые сверху. Элементы внутри каждой недели сгруппированы по категориям. Всё, что затрагивает публичный API (поверхность CLI, маршруты сокета, формы ответов), также попадает в [Контракт API](/API-CONTRACT) — changelog является указателем, а не заменой. - -## Неделя от 11 мая 2026 - -### Новые возможности - -- **TUI Coven, ориентированный на промпты.** Запуск `coven` (или `coven tui`) теперь открывает интерактивный интерфейс на основе Ratatui. Вводите задачи в свободной форме, выполняйте slash-команды (`/help`, `/agent`, `/clear`, `/export`, `/exit`) и навигируйте по меню ритуалов клавишами со стрелками. Работает через SSH и безопасно меняет размер. См. [Coven TUI](/start/coven-tui). -- **Диагностика и облегчение `coven pc`.** Инструмент давления на систему, ориентированный в первую очередь на macOS. Команды только для чтения показывают снимки CPU, памяти, диска и топовых процессов; операции записи (`coven pc kill`, `coven pc cache clear`) требуют явного `--confirm`. См. [справочник CLI](/reference/cli) и [Troubleshooting](/TROUBLESHOOTING). -- **Контракт локального API v1.** Socket API демона теперь предоставляет версионированные эндпоинты health и capabilities, структурированные ответы об ошибках и пагинацию событий на основе курсора. Клиенты могут согласовывать возможности, а не угадывать их. См. [API contract](/API-CONTRACT) и [Local API](/API). -- **JSON-вывод сессий.** `coven sessions --json` выдаёт машиночитаемые списки сессий для скриптов, дашбордов и внешних клиентов. См. [comux JSON sessions](/sessions/comux-json). -- **Путь установки в Windows.** Coven теперь поставляет npm-пакет для Windows, так что `npx @opencoven/cli` работает на нативном Windows наряду с macOS и Linux. См. [Getting started](/GETTING-STARTED). - -### Обновления - -- **Позиционирование и брендинг OpenCoven.** Обновлены продуктовые тексты в документации и CLI, чтобы представить Coven как экосистему для постоянных AI-фамильяров, с обновлёнными брендовыми токенами и дизайн-руководством. См. [Бренд](/BRAND). -- **Обновлённая палитра бренда.** Палитра OpenCoven обновлена до приглушённого лавандово-серого (`#9A8ECD`) с новой системой комплементарных акцентов и выделенными токенами поверхностей для тёмной и светлой темы. Существующие легаси-алиасы цветов сохранены, поэтому никаких действий для перехода на новый вид не требуется. См. [Бренд](/BRAND). -- **Тема TUI в фирменном стиле.** TUI Coven теперь использует единую тему, согласованную с палитрой OpenCoven. Изящные фолбэки для терминалов без цвета, 256-цветных и truecolor сохраняют её читаемость локально, по SSH и в CI. См. [Coven TUI](/start/coven-tui). -- **Troubleshooting: здоровье и давление системы.** Добавлен раздел, который ведёт из канонического потока troubleshooting к `coven pc` для диагностики локального давления на CPU, память и диск. См. [Troubleshooting](/TROUBLESHOOTING). -- **Полные идентификаторы сессий в plain-выводе.** `coven sessions --plain` теперь печатает полные идентификаторы сессий, чтобы их можно было копировать прямо в последующие команды. - -### Исправления ошибок - -- **Проверка статуса демона.** `coven` теперь проверяет демон через его health-сокет перед тем, как сообщить `running`, очищает мёртвые устаревшие метаданные и сообщает `stale`, когда метаданные живы, но не проверены. -- **Восстановление при повреждённых метаданных демона.** CLI теперь корректно восстанавливается, когда метаданные статуса демона на диске повреждены, вместо того чтобы не запускаться. -- **Более строгая пагинация событий.** API отклоняет нецелочисленные значения `limit` и `afterSeq` со структурированной ошибкой `invalid_request` до того, как выполнять какой-либо поиск сессии. -- **Ложные срабатывания guard'а секретов релиза.** Guard секретов публичного релиза теперь разрешает документированные ссылки на репозиторий OpenCoven и локальные пути worktree как безобидные токены с высокой энтропией, продолжая при этом помечать явные паттерны секретов. diff --git a/docs/ru/reference/releasing.md b/docs/ru/reference/releasing.md deleted file mode 100644 index e66cef5a..00000000 --- a/docs/ru/reference/releasing.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -summary: "Поток релизов для @opencoven/cli и пакетов платформ." -read_when: - - Cutting a release -title: "Выпуск релизов" -description: "Руководство для операторов: как публиковать Coven в npm — preflight-проверки, dry-run, выпуск CLI-wrapper и нативных пакетов, postflight-проверка." ---- - -Coven публикует npm-wrapper и нативные платформенные пакеты из workflow GitHub Actions **Release npm packages**. Версии исходных пакетов остаются `0.0.0`; версия dispatch'а workflow — это публикуемая npm-версия. - -## Preflight - -Перед публикацией: - -1. Убедитесь, что нет открытых PR, которые должны попасть в релиз. -2. Убедитесь, что CI `main` зелёный для точного коммита, который вы будете релизить. -3. Проверьте в npm текущие `latest`-версии: - -```sh -npm view @opencoven/cli version dist-tags -npm view @opencoven/cli-macos version dist-tags -npm view @opencoven/cli-linux-x64 version dist-tags -npm view @opencoven/cli-windows version dist-tags -``` - -4. Убедитесь, что changelog, статусный текст README пакета и брендовые ассеты соответствуют релизу. - -## Dry Run - -Сначала запустите workflow с `publish=false`. Это соберёт все платформенные бинарники и выполнит dry-run'ы npm publish без необходимости в npm-учётных данных: - -```sh -gh workflow run release-npm.yml \ - --ref main \ - -f publish=false \ - -f version=0.0.13 -``` - -Следите за запуском: - -```sh -gh run list --workflow release-npm.yml --branch main --limit 1 -gh run watch -``` - -## Publish - -Публикуйте только после того, как dry-run пройдёт успешно, а версии npm-пакетов всё ещё доступны: - -```sh -gh workflow run release-npm.yml \ - --ref main \ - -f publish=true \ - -f version=0.0.13 -``` - -Job публикации использует окружение `npm-publish` и `NPM_ACCESS_TOKEN`. Сначала публикуются нативные пакеты (`@opencoven/cli-linux-x64`, `@opencoven/cli-windows`, `@opencoven/cli-macos`), а затем wrapper-пакет (`@opencoven/cli`). - -## Postflight - -После завершения запуска публикации: - -```sh -npm view @opencoven/cli version dist-tags -npm view @opencoven/cli-macos version dist-tags -npm view @opencoven/cli-linux-x64 version dist-tags -npm view @opencoven/cli-windows version dist-tags -``` - -Если какой-либо пакет не опубликовался, не запускайте повторно вслепую. Изучите упавший job, подтвердите, какие версии пакета существуют в npm, и перезапускайте только с новой версией, если npm уже принял часть релиза. diff --git a/docs/ru/start/coven-tui.md b/docs/ru/start/coven-tui.md deleted file mode 100644 index 7443b2c9..00000000 --- a/docs/ru/start/coven-tui.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -summary: "Интерактивное prompt-first меню, запускаемое `coven` или `coven tui`." -read_when: - - Просмотр того, что может делать интерактивное меню Coven - - Изучение slash-команд и сокращений - - Решение, использовать ли TUI или низкоуровневые глаголы CLI -title: "TUI Coven" -description: "Используй prompt-first TUI Coven для запуска harness-сессий, просмотра выполняющейся работы, подключения к сессиям и срабатывания ритуалов из одного меню." ---- - -`coven` (или явное `coven tui`) открывает **prompt-first TUI**: интерфейс, основанный на Ratatui, где можно вводить задачи в свободной форме, запускать slash-команды или навигировать по меню ритуалов стрелками. Это рекомендуемая отправная точка для новых пользователей, и она работает через SSH или в локальном терминале. - -## Когда её использовать - -| Ситуация | Лучшая поверхность | -|---|---| -| Свежая установка, изучение того, что Coven может делать | **TUI** (`coven`) | -| Разовая задача в знакомом проекте | **TUI** или `coven run ""` | -| Скриптинг, пайпинг, читаемый машиной вывод | `coven sessions --json`, `--plain` | -| Долгий attach/replay | Браузер сессий TUI или `coven attach ` | -| Быстрая проверка здоровья | `coven doctor` | - -TUI — это тонкий слой представления. Каждое действие, которое она предлагает, отображается на базовый глагол CLI или вызов socket API — демон на Rust остаётся авторитетом. - -## Анатомия - -```mermaid -flowchart TB - subgraph TUI["coven TUI"] - Input["Prompt-first input bar\n(free text + slash commands)"] - Browser["Session browser pane"] - Help["Help / shortcuts overlay"] - end - Input -->|free text| LaunchPath["coven run "] - Input -->|slash command| Dispatch["/run, /sessions, /archive, ..."] - Browser -->|Rejoin| Attach["coven attach"] - Browser -->|Archive| Archive["coven archive"] - Browser -->|Summon| Summon["coven summon"] - Browser -->|Sacrifice| Sacrifice["coven sacrifice"] - LaunchPath --> Daemon[Coven daemon] - Dispatch --> Daemon - Attach --> Daemon - Archive --> Daemon - Summon --> Daemon - Sacrifice --> Daemon -``` - -TUI никогда не обходит демон. Корень проекта, cwd и id harness'а перепроверяются на стороне сервера при каждом запуске. - -## Режимы input - -Строка prompt принимает три формы input взаимозаменяемо: - -1. **Свободный текст задачи** — всё, что **не** начинается с `/`. Нажатие `Enter` запускает harness по умолчанию против текущего проекта. - - ```text - fix the failing tests - review the diff in packages/cli - ``` - -2. **Slash-команды** — начинаются с `/` и маршрутизируются к конкретному глаголу. - - ```text - /run codex "audit this repo" - /run claude "polish the help text" --title "Help polish" - /sessions - /archive session-1 - /help - ``` - -3. **Навигация меню стрелками** — `↑` / `↓` циклически проходят через карты ритуалов (Rejoin, View Log, Summon, Archive, Sacrifice) для выбранной в данный момент сессии. `Enter` подтверждает. `Esc` отменяет. - -## Справочник slash-команд - -| Команда | Что делает | -|---|---| -| `/help` | Показывает overlay помощи со всеми сокращениями и примерами. | -| `/run ""` | Запускает сессию, ограниченную проектом. Так же, как `coven run`. | -| `/sessions` | Открывает браузер сессий. Так же, как `coven sessions`. | -| `/attach ` | Подключиться к (или воспроизвести) сессии. | -| `/archive ` | Скрыть не выполняющуюся сессию, сохраняя события. | -| `/summon ` | Восстановить архивную сессию. | -| `/sacrifice ` | Навсегда удалить не выполняющуюся сессию. Просит ввести `sacrifice` для подтверждения. | -| `/doctor` | Запустить `coven doctor` и отрендерить результат inline. | -| `/clear` | Очистить строку input и любой inline-вывод. | -| `/export` | Скопировать запись текущей выбранной сессии как JSON в буфер обмена. | -| `/agent ` | Установить harness по умолчанию для свободного input в этой сессии TUI. | -| `/exit` | Чисто закрыть TUI. Эквивалент `Ctrl+C` или `Esc` в корне. | - -## Клавиатурные сокращения - -| Клавиши | Действие | -|---|---| -| `h` (корень) | Открывает overlay `/help` | -| `↑ / ↓` | Перемещает выбор в браузере сессий или меню | -| `Enter` | Подтверждает выбор / отправляет prompt | -| `Esc` | Возврат из меню или выход в корне | -| `Ctrl+C` | Немедленный выход | -| `Tab` | Циклическое переключение фокуса между строкой input и браузером сессий | -| `Ctrl+L` | Перерисовка (полезно через нестабильный SSH) | - -TUI безопасно изменяет размер. Терминалы, такие маленькие, как 80×24, остаются пригодными к использованию; более широкие терминалы автоматически расширяют список сессий, предпросмотр логов и overlay помощи. - -## Действия браузера сессий - -Выбор сессии и нажатие `Enter` показывает контекстные действия. Каждое ограничено состоянием сессии — действия, которые небезопасны для текущего состояния, скрываются, а не делаются серыми, поэтому меню никогда не предлагает разрушительный глагол, который ты не можешь выполнить. - -| Действие | Доступно когда | Эффект | -|---|---|---| -| **Rejoin** | сессия `running` | Подключение к живому PTY; input пересылается в harness. | -| **View Log** | сессия не `running` | Воспроизведение журнала событий (только для чтения). | -| **Summon** | `archived_at` установлен | Восстановить в активный список и воспроизвести/следить. | -| **Archive** | сессия не `running` и не архивирована | Скрыть из активного списка; события сохраняются. | -| **Sacrifice** | сессия не `running` | Постоянное удаление; требует ввод подтверждения. | - -Отображение между действиями и глаголами CLI задокументировано в [Жизненный цикл сессии](/SESSION-LIFECYCLE). - -## SSH и удалённое использование - -TUI основана на Ratatui и переживает обычные враждебные окружения: - -- Терминалы через SSH (без локальных зависимостей мыши/шрифта). -- Изменение размера во время сессии (перерисовывает на `SIGWINCH`). -- `TERM=xterm-256color` или `screen-256color`. - -Она **не** требует графического терминала, бэкенда буфера обмена или `tmux`. Если ты внутри `tmux` или `screen`, TUI ведёт себя как любое другое приложение Ratatui — splits панелей и detach по-прежнему работают. - -## Fallback в plain-text - -Если предпочитаешь неинтерактивный поток (CI, скриптинг, логи аудита), пропусти TUI полностью: - -```bash -coven run codex "fix the failing tests" -coven sessions --plain -coven attach -``` - -Эти глаголы производят стабильный, скриптуемый вывод, и это те же глаголы, к которым TUI в конечном итоге маршрутизирует. - - - -## Связанное - -- [Начать работу с Coven](/GETTING-STARTED) -- [Жизненный цикл сессии](/SESSION-LIFECYCLE) -- [Справочник CLI](/reference/cli) -- [Решение проблем](/TROUBLESHOOTING) diff --git a/docs/ru/superpowers/plans/2026-05-15-tui-chat-module.md b/docs/ru/superpowers/plans/2026-05-15-tui-chat-module.md deleted file mode 100644 index bee99c06..00000000 --- a/docs/ru/superpowers/plans/2026-05-15-tui-chat-module.md +++ /dev/null @@ -1,655 +0,0 @@ ---- -title: "План внедрения: выделение модуля чата TUI в coven-cli" -description: "План на русском по разделению chat.rs (1111 строк) в модуль tui/ внутри coven-cli за три коммита без изменения поведения и добавления новых зависимостей." ---- - -# План внедрения выделения модуля чата TUI - -> **Для агентных работников:** ТРЕБУЕМЫЙ ПОД-НАВЫК: Используйте superpowers:subagent-driven-development (рекомендуется) или superpowers:executing-plans для реализации этого плана задача за задачей. Шаги используют синтаксис чекбоксов (`- [ ]`) для отслеживания. - -**Цель:** Разделить `crates/coven-cli/src/chat.rs` (1111 строк) на 4-файловый модуль под новым пространством имён `tui/`, с нулевыми изменениями поведения. - -**Архитектура:** Чистое перемещение кода. Три последовательных коммита: (1) каркас пустых новых файлов + подключение `mod tui;` в main.rs, (2) перемещение всего содержимого из `chat.rs` в новые файлы, превращая `chat.rs` в шим реэкспорта, (3) удаление `chat.rs` + стража и обновление точки вызова `main.rs`. - -**Технический стек:** Rust edition 2021. Без новых зависимостей. Те же ratatui 0.30 / crossterm 0.29, что и в Фазе 1. - -**Спецификация:** [`docs/superpowers/specs/2026-05-15-tui-chat-module-design.md`](../specs/2026-05-15-tui-chat-module-design.md) - -**Ветка:** `feat/tui-chat-module`, накладывается на `feat/tui-theme-module`. PR не может быть слит, пока не приземлится #56. - -**Worktree:** `/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module` - ---- - -## Карта файлов - -| Файл | Действие | Заметки | -|---|---|---| -| `crates/coven-cli/src/tui/mod.rs` | **Создать** (~10 строк) | Док-комментарий уровня модуля + `pub mod chat;` | -| `crates/coven-cli/src/tui/chat/mod.rs` | **Создать** (~40 строк) | `pub fn run_chat` + реэкспорты `MessageRole`/`ChatMessage`/`AgentInfo` | -| `crates/coven-cli/src/tui/chat/app.rs` | **Создать** (~530 строк) | Всё состояние, поведение, хелперы, тесты | -| `crates/coven-cli/src/tui/chat/render.rs` | **Создать** (~380 строк) | Все 7 функций `render_*` | -| `crates/coven-cli/src/tui/chat/events.rs` | **Создать** (~150 строк) | `run_event_loop` | -| `crates/coven-cli/src/chat.rs` | **Удалить** (сейчас 1111 строк) | Заменяется модулем выше | -| `crates/coven-cli/src/main.rs` | **Изменить** (~2 строки) | `mod chat;` → `mod tui;` (алфавитное переупорядочивание); `chat::run_chat()` → `tui::chat::run_chat()` | - -Никакие другие файлы не меняются. Тесты не добавляются; один тест (страж) удаляется. - ---- - -## Критическая заметка о рабочем каталоге - -ВСЕ команды `cd`, `cargo` и `git` в этом плане выполняются из: - -``` -/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -``` - -Первое действие в каждой задаче — сделать `cd` туда и убедиться, что `git rev-parse --abbrev-ref HEAD` равно `feat/tui-chat-module`. В противном случае ОСТАНОВИТЬСЯ и сообщить ЗАБЛОКИРОВАНО. (Это урок из Фазы 1, когда некоторые субагенты-реализаторы случайно писали в основной checkout.) - ---- - -## Задача 1: Каркас новой структуры модуля - -Создать пустые/скелетные файлы для нового модуля и подключить его к `main.rs`. После этой задачи и `mod chat;` (указывающий на старый `chat.rs`), и `mod tui;` (указывающий на новый, почти пустой модуль) сосуществуют. Сборка проходит с предупреждениями о неиспользуемых элементах в новых файлах. - -**Файлы:** -- Создать: `crates/coven-cli/src/tui/mod.rs` -- Создать: `crates/coven-cli/src/tui/chat/mod.rs` -- Создать: `crates/coven-cli/src/tui/chat/app.rs` -- Создать: `crates/coven-cli/src/tui/chat/render.rs` -- Создать: `crates/coven-cli/src/tui/chat/events.rs` -- Изменить: `crates/coven-cli/src/main.rs` (добавить объявление `mod tui;`) - -- [ ] **Шаг 1: cd в worktree и проверка ветки** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -pwd -git rev-parse --abbrev-ref HEAD -``` - -Ожидается: -``` -/Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -feat/tui-chat-module -``` - -Если что-то отличается, ОСТАНОВИТЬСЯ и сообщить ЗАБЛОКИРОВАНО. Не модифицировать файлы вне этого worktree. - -- [ ] **Шаг 2: Создать `crates/coven-cli/src/tui/mod.rs`** - -Записать точно это содержимое: - -```rust -//! TUI surfaces for the coven CLI. Currently hosts the chat module; Phases 3–4 -//! will land the launcher and session-browser carve-outs from main.rs here. - -pub mod chat; -``` - -- [ ] **Шаг 3: Создать `crates/coven-cli/src/tui/chat/mod.rs` как временную заглушку** - -Этот файл — заглушка для Задачи 1. Он будет наполнен `run_chat` и реэкспортами в Задаче 2. Пока он должен компилироваться без предупреждений, хотя ничто ещё не ссылается на его подмодули. - -Записать точно это содержимое: - -```rust -//! Ratatui-based chat TUI. State lives in `app`, view in `render`, event loop -//! in `events`. The entry point `run_chat` here manages the raw-terminal -//! lifecycle. - -#![allow(dead_code)] - -mod app; -mod events; -mod render; -``` - -`#![allow(dead_code)]` временный — он удаляется на Шаге 5 Задачи 2, когда `run_chat` приземляется здесь и потребляет подмодули. Подмодули объявлены приватными (`mod`, а не `pub mod`), потому что ни одному коду вне `tui::chat` не нужно лезть в `tui::chat::app::*`. - -- [ ] **Шаг 4: Создать три пустых файла подмодулей** - -Каждый должен быть валидным Rust, который компилируется самостоятельно. Запишите каждый файл только с док-комментарием и строкой `// placeholder` (заменяется в Задаче 2): - -**`crates/coven-cli/src/tui/chat/app.rs`:** - -```rust -//! Chat application state, behavior, and tests. Populated in Task 2 of the -//! chat-module carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -**`crates/coven-cli/src/tui/chat/render.rs`:** - -```rust -//! Chat TUI render functions. Populated in Task 2 of the chat-module -//! carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -**`crates/coven-cli/src/tui/chat/events.rs`:** - -```rust -//! Chat TUI event loop. Populated in Task 2 of the chat-module -//! carve-out (see plans/2026-05-15-tui-chat-module.md). - -// placeholder — content lands in Task 2 -``` - -- [ ] **Шаг 5: Добавить `mod tui;` в main.rs** - -Найти этот блок в `crates/coven-cli/src/main.rs` (около строк 31–33 после вставки `mod theme;` из Фазы 1): - -```rust -mod store; -mod theme; -mod verification; -``` - -Вставить `mod tui;` алфавитно между `theme` и `verification`: - -```rust -mod store; -mod theme; -mod tui; -mod verification; -``` - -НЕ удалять `mod chat;` пока (этим занимается Задача 3). Оба модуля сосуществуют после Задачи 1. - -- [ ] **Шаг 6: Проверить, что крейт собирается** - -```bash -cargo build -p coven-cli 2>&1 | tail -20 -``` - -Ожидается: собирается чисто. Несколько предупреждений «unused import» о `crate::tui::chat` или его подмодулях допустимы в Задаче 1 — они будут потреблены в Задаче 3. - -Если вы видите реальные ошибки (не предупреждения), ОСТАНОВИТЬСЯ и сообщить ЗАБЛОКИРОВАНО с текстом ошибки. - -- [ ] **Шаг 7: Запустить все тесты** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Ожидается: все существующие тесты проходят. Модуль chat (всё ещё в `src/chat.rs`) и его тесты не тронуты. Количество тестов: 172 unit + 4 smoke = 176 (как в конце Фазы 1). - -- [ ] **Шаг 8: Коммит** - -```bash -git add crates/coven-cli/src/tui/ crates/coven-cli/src/main.rs -git commit -m "refactor(tui): scaffold tui/chat module structure - -Empty submodule skeleton for the chat carve-out. Old chat.rs remains -the active implementation; this commit only adds the new file tree and -wires mod tui; into main.rs. Task 2 of the chat-module plan moves the -content; Task 3 deletes the old file. -" -``` - -- [ ] **Шаг 9: Убедиться, что коммит приземлился на правильной ветке** - -```bash -git log --oneline -2 -git rev-parse --abbrev-ref HEAD -``` - -Ожидается: новый коммит сверху, и HEAD на `feat/tui-chat-module`. Если нет, ОСТАНОВИТЬСЯ и сообщить. - ---- - -## Задача 2: Переместить всё содержимое из `chat.rs` в новые файлы модуля - -Это основная часть работы. Стратегия: копировать каждый раздел старого `chat.rs` в его целевой новый файл, исправить импорты + видимость, затем заменить `chat.rs` на шим реэкспорта (`pub use crate::tui::chat::*;`), чтобы старая точка вызова `chat::run_chat()` в `main.rs` продолжала работать в течение Задачи 2. Задача 3 удаляет шим и обновляет точку вызова. - -**Файлы:** -- Изменить: `crates/coven-cli/src/tui/chat/mod.rs` (заменить заглушку на run_chat + реэкспорты) -- Изменить: `crates/coven-cli/src/tui/chat/app.rs` (заменить placeholder кодом состояния) -- Изменить: `crates/coven-cli/src/tui/chat/render.rs` (заменить placeholder рендерерами) -- Изменить: `crates/coven-cli/src/tui/chat/events.rs` (заменить placeholder циклом событий) -- Изменить: `crates/coven-cli/src/chat.rs` (свести к шиму реэкспорта) - -- [ ] **Шаг 1: cd в worktree и проверка ветки** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -git rev-parse --abbrev-ref HEAD -``` - -Ожидается: `feat/tui-chat-module`. Иначе ОСТАНОВИТЬСЯ. - -- [ ] **Шаг 2: Наполнить `tui/chat/app.rs`** - -Открыть `crates/coven-cli/src/chat.rs` и скопировать следующие диапазоны (номера строк относятся к **текущему** chat.rs на момент коммита `9bcb69a`): - -- Строки 33–85 (типы данных: `MessageRole`, `ChatMessage`, `AgentInfo`, `InputMode`, `SlashCommandResult`, `App`) -- Строка 86 (константа `SPINNER_FRAMES`) -- Строки 88–457 (блок `impl App`) -- Строки 459–471 (`fn discover_agents`) -- Строки 990–992 (`fn timestamp_now`) -- Строки 994–1002 (`fn truncate_str`) -- Строки 1004–1111 (весь блок `#[cfg(test)] mod tests`) - -Заменить placeholder в `crates/coven-cli/src/tui/chat/app.rs` этим содержимым в таком порядке: - -1. Док-комментарий в начале файла + операторы use (заменить импорты из chat.rs только тем, что нужно app.rs): - -```rust -//! Chat application state, behavior, and helpers. Owns `App` and all of its -//! methods; provides `discover_agents` and the spinner-frame data. - -use crate::harness; -``` - -2. Типы данных из строк 33–69 файла chat.rs. **Изменения видимости (из спецификации):** - - `pub enum MessageRole` → оставить `pub` (реэкспортирован через mod.rs на следующем шаге) - - `pub struct ChatMessage` → оставить `pub` - - `pub struct AgentInfo` → оставить `pub` - - `enum InputMode` → без изменений (приватный, остаётся `enum`) - - `enum SlashCommandResult` → без изменений (приватный) - -3. `struct App` (строки 71–85): изменить видимость с приватной на `pub(super)`: - -```rust -pub(super) struct App { - // ... unchanged fields ... -} -``` - -4. `const SPINNER_FRAMES: &[&str] = ...` (строка 86): изменить на `pub(super)`: - -```rust -pub(super) const SPINNER_FRAMES: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧"]; -``` -(Или скопировать точные глифы из chat.rs:86 — кадры спиннера — это те же символы шаблона Брайля.) - -5. `impl App` (строки 88–457): вставить без изменений. - -6. `fn discover_agents` (строки 459–471): изменить на `pub(super)`: - -```rust -pub(super) fn discover_agents() -> Vec { - // ... unchanged body ... -} -``` - -7. `fn timestamp_now` (строки 990–992): оставить приватной: - -```rust -fn timestamp_now() -> String { - // ... unchanged body ... -} -``` - -8. `fn truncate_str` (строки 994–1002): оставить приватной: - -```rust -fn truncate_str(s: &str, max: usize) -> &str { - // ... unchanged body ... -} -``` - -9. Модуль тестов (строки 1004–1111) — вставить с такими точечными изменениями: - - **Удалить** тест `chat_module_stays_single_file_to_avoid_rust_module_ambiguity` (строки 1035–1059). - - **Удалить** импорт `use std::path::Path;` внутри `mod tests` (только этот тест его использовал; другие нет). - - Сохранить все четыре поведенческих теста (`unknown_slash_command_returns_command_name_for_feedback`, `handle_input_clears_unknown_slash_command_and_reports_it`, `agent_command_without_argument_opens_picker_on_active_agent`, `unavailable_agent_selection_keeps_current_active_agent`) и оба хелпера (`app_with_agents`, `agent`) без изменений. - -- [ ] **Шаг 3: Наполнить `tui/chat/render.rs`** - -Скопировать следующие диапазоны из `chat.rs` в новый `render.rs`: - -- Строки 473–510 (`fn render_ui`) -- Строки 512–538 (`fn render_status_bar`) -- Строки 540–636 (`fn render_messages`) -- Строки 638–672 (`fn render_input`) -- Строки 674–700 (`fn render_hint_bar`) -- Строки 702–779 (`fn render_help_overlay`) -- Строки 781–838 (`fn render_agent_select`) - -Заменить placeholder в `render.rs` на: - -1. Док-комментарий в начале файла + импорты. Рендерерам нужны типы ratatui и модуль theme: - -```rust -//! Chat TUI render functions. Pure view code; reads `App` state and emits -//! ratatui widgets. The entry point is `render_ui`; the other render_* fns -//! are private helpers it composes. - -use ratatui::{ - Frame, - layout::{Alignment, Constraint, Layout, Margin, Rect}, - style::{Color, Style}, - text::{Line, Span}, - widgets::{Block, Borders, Clear, List, ListItem, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, Wrap}, -}; - -use crate::theme::{self, AGENT_LABEL, DIM, HINT_KEY, PRIMARY, PRIMARY_STRONG, SURFACE, SURFACE_STRONG, USER_LABEL}; - -use super::app::{App, AgentInfo, InputMode, MessageRole, SPINNER_FRAMES}; -``` - -2. Изменить `fn render_ui` на `pub(super) fn render_ui` (вызывается `events.rs` далее): - -```rust -pub(super) fn render_ui(f: &mut Frame, app: &mut App) { - // ... unchanged body ... -} -``` - -3. Все остальные функции `render_*` остаются приватными (`fn`, не `pub`). Вставить их без изменений. - -- [ ] **Шаг 4: Наполнить `tui/chat/events.rs`** - -Скопировать строки 863–988 из `chat.rs` (функцию `run_event_loop`) в `events.rs`. - -Заменить placeholder на: - -```rust -//! Chat TUI event loop. Reads keyboard events via crossterm and dispatches -//! to `App` methods; calls `render_ui` between events. - -use std::io::Stdout; -use std::time::{Duration, Instant}; - -use anyhow::Result; -use crossterm::event::{self, Event, KeyCode, KeyModifiers}; -use ratatui::{Terminal, backend::CrosstermBackend}; - -use super::app::{App, SlashCommandResult}; -use super::render::render_ui; -``` - -Затем вставить `run_event_loop` с таким изменением сигнатуры: - -```rust -pub(super) fn run_event_loop( - terminal: &mut Terminal>, - app: &mut App, -) -> Result<()> { - // ... unchanged body ... -} -``` - -(Сегодняшняя сигнатура в chat.rs строка 863 начинает тело с параметров `terminal:` и `app:` — сохранить их.) - -- [ ] **Шаг 5: Наполнить `tui/chat/mod.rs`** - -Заменить заглушку, созданную в Задаче 1, реальным содержимым. mod.rs содержит `run_chat` и публичные реэкспорты. - -```rust -//! Ratatui-based chat TUI. State lives in `app`, view in `render`, event loop -//! in `events`. The entry point `run_chat` manages the raw-terminal lifecycle. - -mod app; -mod events; -mod render; - -// Re-export the public types so callers see them at `tui::chat::*` instead of -// having to reach into `tui::chat::app::*`. Matches the surface of the old -// `chat::*` module from before the carve-out. -pub use app::{AgentInfo, ChatMessage, MessageRole}; - -use std::io::stdout; - -use anyhow::Result; -use crossterm::{ - event::{DisableMouseCapture, EnableMouseCapture}, - execute, - terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, -}; -use ratatui::{backend::CrosstermBackend, Terminal}; - -use app::App; -use events::run_event_loop; -``` - -Затем вставить тело `pub fn run_chat()` из chat.rs строк 840–861 без изменений. Тело вызывает `App::new()` и `run_event_loop(...)` — оба импортированы в блоке `use` выше, поэтому правки тела не требуются. - -Удалить `#![allow(dead_code)]` из верха mod.rs, который был добавлен в Задаче 1. - -- [ ] **Шаг 6: Заменить `chat.rs` шимом реэкспорта** - -Заменить всё содержимое `crates/coven-cli/src/chat.rs` (1111 строк) на эти 3 строки: - -```rust -//! Temporary re-export shim during the Phase 2 carve-out. Removed in Task 3 -//! of the chat-module plan; do not add new content here. - -pub use crate::tui::chat::*; -``` - -Это сохраняет работоспособность точки вызова `chat::run_chat()` в `main.rs` (теперь она разрешается в `tui::chat::run_chat` через глоб-реэкспорт). Шим удаляется в Задаче 3. - -- [ ] **Шаг 7: Проверить, что крейт собирается** - -```bash -cargo build -p coven-cli 2>&1 | tail -30 -``` - -Ожидается: собирается чисто без ошибок. Могут остаться некоторые предупреждения (например, «unused import», если `use` теперь избыточен). Если вы видите ошибки, наиболее вероятная причина: - -- Элемент `pub(super)`, которому нужен `pub` для реэкспорта через шим. Шим chat.rs `pub use crate::tui::chat::*;` реэкспортирует только `pub` элементы, не `pub(super)`. Элементы `run_chat`, `MessageRole`, `ChatMessage`, `AgentInfo` должны быть `pub` в `tui::chat::*`, чтобы шим их нашёл. -- Отсутствующий импорт в одном из новых файлов. Сверьте раздел импортов в каждом файле с тем, что перечислено в спецификации. - -- [ ] **Шаг 8: Запустить все тесты** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Ожидается: **175 unit-тестов** + 4 smoke-теста проходят (на один unit-тест меньше, чем в начале Задачи 2 — удалённый страж). - -Если тест падает, наиболее вероятная причина — файл тестов больше не компилируется (приватный доступ к полям `App` раньше был легален, но теперь требует, чтобы тест был в том же файле, что и `App` — он там, в `app.rs`, так что это должно работать). - -- [ ] **Шаг 9: Коммит** - -```bash -git add crates/coven-cli/src/tui/ crates/coven-cli/src/chat.rs -git commit -m "refactor(tui): move chat.rs content into tui/chat/* submodule - -Pure code motion. chat.rs becomes a re-export shim that points at -crate::tui::chat::* so main.rs's existing chat::run_chat() call keeps -working. The shim and the old mod chat; declaration get deleted in -Task 3 along with the guardrail test (which fails as soon as chat.rs -is removed). -" -``` - -- [ ] **Шаг 10: Проверить коммит на правильной ветке** - -```bash -git log --oneline -3 -git rev-parse --abbrev-ref HEAD -``` - -Ожидается: новый коммит сверху, HEAD = `feat/tui-chat-module`. - ---- - -## Задача 3: Удалить `chat.rs` и обновить `main.rs` - -После Задачи 2 `chat.rs` — просто шим реэкспорта. Эта задача удаляет его, убирает `mod chat;` из main.rs, обновляет точку вызова на `tui::chat::run_chat()` и проверяет финальные критерии приёмки. - -**Файлы:** -- Удалить: `crates/coven-cli/src/chat.rs` -- Изменить: `crates/coven-cli/src/main.rs` (удалить `mod chat;`, обновить строку 150) - -- [ ] **Шаг 1: cd в worktree, проверка ветки** - -```bash -cd /Users/buns/Documents/GitHub/OpenCoven/coven/.worktrees/feat-tui-chat-module -git rev-parse --abbrev-ref HEAD -``` - -Ожидается: `feat/tui-chat-module`. - -- [ ] **Шаг 2: Удалить `crates/coven-cli/src/chat.rs`** - -```bash -rm crates/coven-cli/src/chat.rs -git status --short -``` - -Ожидается: показывает `D crates/coven-cli/src/chat.rs`. - -- [ ] **Шаг 3: Обновить `main.rs` — удалить `mod chat;`** - -В `crates/coven-cli/src/main.rs` найти блок объявлений `mod` (около строк 21–35). Удалить строку `mod chat;`. Оставшийся блок mod должен выглядеть так: - -```rust -mod api; -mod control_plane; -mod daemon; -mod harness; -mod openclaw_repo; -mod patch; -mod pc; -mod project; -mod pty_runner; -mod store; -mod theme; -mod tui; -mod verification; -``` - -(Заметка: `mod chat;` изначально находился между `mod api;` и `mod control_plane;`.) - -- [ ] **Шаг 4: Обновить `main.rs` — изменить точку вызова chat** - -В `main.rs` найти строку 150 (приблизительно — точная строка смещается при удалении `mod chat;`): - -```rust -Some(Command::Chat) => chat::run_chat(), -``` - -Заменить на: - -```rust -Some(Command::Chat) => tui::chat::run_chat(), -``` - -Это **единственная** точка вызова в main.rs, использующая модуль chat. Подтвердить через grep: - -```bash -grep -nE '\bchat::' crates/coven-cli/src/main.rs -``` - -Ожидаемый вывод: одна строка, новый `tui::chat::run_chat()`. Если вы видите дополнительные совпадения, их тоже нужно заменить. - -- [ ] **Шаг 5: Проверить, что крейт собирается** - -```bash -cargo build -p coven-cli 2>&1 | tail -20 -``` - -Ожидается: собирается чисто с нулём предупреждений. - -Если вы видите: -- «unresolved module `chat`» — вы пропустили Шаг 3 (удаление `mod chat;`) или Шаг 4 (обновление точки вызова). Повторно сделать grep. -- «file not found: chat.rs» — сборка всё ещё ищет chat.rs. Подтвердите, что `mod chat;` ушёл из main.rs. -- «function `run_chat` is private» — `run_chat` в `tui/chat/mod.rs` не `pub`. Проверьте содержимое `mod.rs` из Задачи 2; требуется сигнатура `pub fn run_chat`. - -- [ ] **Шаг 6: Запустить все тесты** - -```bash -cargo test -p coven-cli 2>&1 | tail -10 -``` - -Ожидается: **175 unit-тестов + 4 smoke-теста проходят** (тот же счёт, что в Задаче 2). - -- [ ] **Шаг 7: Запустить clippy** - -```bash -cargo clippy -p coven-cli --no-deps 2>&1 | tail -10 -``` - -Ожидается: ноль предупреждений (без регрессии относительно чистого состояния Фазы 1). - -- [ ] **Шаг 8: Проверить критерии приёмки через проверки файловой системы** - -```bash -# Criterion 1: chat.rs is gone -test -e crates/coven-cli/src/chat.rs && echo "FAIL: chat.rs still exists" || echo "ok: chat.rs deleted" - -# Criterion 2: tui/mod.rs exists with the expected content -cat crates/coven-cli/src/tui/mod.rs - -# Criterion 3: tui/chat/ has exactly 4 .rs files -ls crates/coven-cli/src/tui/chat/ - -# Criterion 4: main.rs uses tui::chat::run_chat -grep -nE 'tui::chat::run_chat|chat::run_chat' crates/coven-cli/src/main.rs -``` - -Ожидается: -- `ok: chat.rs deleted` -- `tui/mod.rs` показывает док-комментарий + `pub mod chat;` -- `ls` показывает ровно `mod.rs app.rs render.rs events.rs` (4 файла, без лишних) -- Последний grep показывает одну строку с `tui::chat::run_chat()` - -- [ ] **Шаг 9: Проверить, что удалённый тест-страж исчез** - -```bash -grep -rn 'chat_module_stays_single_file' crates/coven-cli/src/ 2>&1 || echo "ok: guardrail test deleted" -``` - -Ожидается: `ok: guardrail test deleted`. Если что-то совпадает, страж всё ещё где-то существует (он должен был быть удалён при копировании тестов в `app.rs` на Шаге 2 Задачи 2). Удалите его сейчас и перезапустите. - -- [ ] **Шаг 10: Коммит** - -```bash -git add crates/coven-cli/src/main.rs crates/coven-cli/src/chat.rs -git commit -m "refactor(tui): delete chat.rs shim and finalize chat carve-out - -Removes the re-export shim from Task 2, drops mod chat; from main.rs, -and points the Chat command at tui::chat::run_chat() directly. The -guardrail test (which previously prevented this split) was removed in -Task 2 when its containing module file was rewritten. - -Acceptance criteria from the design spec all met: -- src/chat.rs deleted -- src/tui/chat/ has exactly mod.rs, app.rs, render.rs, events.rs -- 175 unit + 4 smoke tests pass -- cargo clippy clean -" -``` - -- [ ] **Шаг 11: Проверить финальное состояние** - -```bash -git log --oneline -4 -git rev-parse --abbrev-ref HEAD -git status --short -``` - -Ожидается: 3 новых коммита поверх вершины Фазы 1 (`9bcb69a`): -``` - refactor(tui): delete chat.rs shim and finalize chat carve-out - refactor(tui): move chat.rs content into tui/chat/* submodule - refactor(tui): scaffold tui/chat module structure -9bcb69a chore(theme): silence dead-code warnings for future-use tokens -``` - -Ветка `feat/tui-chat-module`. Статус чистый (без незакоммиченных изменений). - ---- - -## Готово - -Когда Задача 3 завершена, выполнен каждый критерий приёмки из спецификации: - -1. ✅ `src/chat.rs` больше не существует — Задача 3 Шаг 2. -2. ✅ `src/tui/mod.rs` существует с `pub mod chat;` — Задача 1 Шаг 2. -3. ✅ `src/tui/chat/` содержит ровно `mod.rs`, `app.rs`, `render.rs`, `events.rs` — Задачи 1–2. -4. ✅ `src/main.rs` имеет `mod tui;` и `tui::chat::run_chat()` — Задачи 1 + 3. -5. ✅ `cargo build -p coven-cli` успешно завершается чисто — Задача 3 Шаг 5. -6. ✅ `cargo test -p coven-cli` проходит; счётчик unit падает ровно на один — Задача 3 Шаг 6. -7. ✅ `cargo clippy -p coven-cli --no-deps` выдаёт ноль предупреждений — Задача 3 Шаг 7. -8. ✅ Ни один элемент не получил новой экспозиции за пределами сегодняшней поверхности — правила видимости Задач 2–3. -9. ⏳ Вручную: запуск `coven chat` показывает ту же TUI, что и раньше. Не автоматизируется; проверить на глаз, если удобно. - -После Задачи 3 запушить в origin и открыть PR, накладывающийся на #56. diff --git a/docs/ru/superpowers/specs/2026-05-15-tui-chat-module-design.md b/docs/ru/superpowers/specs/2026-05-15-tui-chat-module-design.md deleted file mode 100644 index 23303687..00000000 --- a/docs/ru/superpowers/specs/2026-05-15-tui-chat-module-design.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: "Проект: выделение модуля чата TUI в coven-cli" -description: "Спецификация на русском фазы 2 очистки TUI: chat.rs делится на состояние, представление, контроллер и жизненный цикл методом чистого перемещения кода." ---- - -# Выделение модуля чата TUI — Проектирование - -**Статус:** Утверждено — готово к плану внедрения -**Дата:** 2026-05-15 -**Область:** Фаза 2 работы по структурной очистке TUI. Накладывается на Фазу 1 ([`feat/tui-theme-module`](https://github.com/OpenCoven/coven/pull/56)); не может быть слита, пока та не приземлится. -**Подход:** Чистое перемещение кода. Без переименований, без изменений сигнатур, без изменений поведения. - ---- - -## Проблема - -`crates/coven-cli/src/chat.rs` содержит 1111 строк после миграции тем в Фазе 1. Это единственный файл, содержащий типы данных чат-TUI на базе ratatui, состояние приложения, ~370 строк кода отрисовки в 7 функциях render, цикл событий, публичную точку входа и тесты. Обязанности файла — модель состояния, представление, контроллер и жизненный цикл — все собраны в одном месте. - -Симптомы, мотивирующие разделение: - -- Файл громоздок для навигации и ревью. Код отрисовки (строки 473–838) — единый непрерывный блок. -- `impl App` (строки 88–457) сам по себе занимает 369 строк. -- Существующий регрессионный тест (`chat_module_stays_single_file_to_avoid_rust_module_ambiguity`, добавленный в `fa786f1`) активно препятствует разделению — его удаление является триггером этой работы. - -Новый модуль `crate::theme`, приземлившийся в Фазе 1, уже демонстрирует паттерн, который мы хотим для поверхностей TUI: одна логическая обязанность на файл, точки вызова импортируют через `use`. - -## Не-цели - -Явно вне области Фазы 2 и не должны вкрадываться: - -- **Изменения поведения** любого рода. Рендереры выдают тот же вывод. Цикл событий обрабатывает те же клавиши. CLI ведёт себя идентично. -- **Сужение API.** `pub enum MessageRole`, `pub struct ChatMessage`, `pub struct AgentInfo` остаются `pub`, хотя сегодня ни один вызывающий код вне модуля chat их не импортирует. Сужение до `pub(super)` — отдельная задача (кандидат на последующий PR; см. Фазу 2.1). -- **Извлечение хелперов.** `render_messages` (самый большой рендерер, ~98 строк) не рефакторится. Внутренние вспомогательные функции не выносятся. -- **Разделение `main.rs`.** Фаза 3 — вне области. -- **Выделение лаунчера / браузера сессий.** Фаза 4 — вне области. (Мы всё же создаём родительский модуль `tui/` на перспективу, но пока под ним живёт только `tui::chat`.) -- **Новые тесты.** Фаза 2 наследует существующие тесты и удаляет ограничительный страж. Новые поведенческие тесты не добавляются. - -## Ограничения - -- **Ни один элемент модуля chat не получает новой экспозиции за пределами `tui::chat::run_chat`.** Видимость сохраняется в точности как сегодня (чистое перемещение кода). -- **Крейт остаётся одним бинарником.** Без новых членов workspace, без библиотечной экспозиции. -- **`cargo clippy -p coven-cli --no-deps` выдаёт ноль предупреждений**, сохраняя чистое состояние после Фазы 1. - -## Структура модуля - -``` -crates/coven-cli/src/ -├── tui/ -│ ├── mod.rs (~10 строк: `pub mod chat;`) -│ └── chat/ -│ ├── mod.rs (~40 строк: pub fn run_chat + жизненный цикл сырого терминала) -│ ├── app.rs (~530 строк: состояние, поведение, хелперы, тесты) -│ ├── render.rs (~380 строк: 7 функций render) -│ └── events.rs (~150 строк: цикл событий) -├── main.rs (одна правка: `mod chat;` → `mod tui;` и `chat::run_chat()` → `tui::chat::run_chat()`) -└── ... (остальные файлы без изменений) -``` - -`crates/coven-cli/src/chat.rs` удаляется полностью. Компилятор Rust запрещает сосуществование `src/chat.rs` и `src/chat/mod.rs`, поэтому удаление однофайловой формы обязательно после появления формы каталога. (Мы используем форму `src/tui/chat/`, а не `src/chat/`, но принцип тот же: никакого `src/chat.rs` оставаться не должно.) - -## Сопоставление содержимого по файлам - -### `tui/mod.rs` (новый) - -```rust -//! TUI surfaces for the coven CLI. Currently hosts the chat module; Phases 3–4 -//! will land the launcher and session-browser carve-outs from main.rs here. - -pub mod chat; -``` - -### `tui/chat/mod.rs` - -Содержит публичную точку входа и жизненный цикл сырого терминала (включить raw-режим, войти в альтернативный экран, построить App, запустить цикл, восстановить терминал при drop). - -| Из `chat.rs` | Новое местоположение | -|---|---| -| Строки 840–861 (`pub fn run_chat`) | `tui/chat/mod.rs` | -| (объявления модулей) | `mod app; mod events; mod render;` | - -Необходимые импорты: -```rust -use std::io::stdout; -use anyhow::Result; -use crossterm::{ - execute, - event::{DisableMouseCapture, EnableMouseCapture}, - terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, -}; -use ratatui::{Terminal, backend::CrosstermBackend}; -``` - -### `tui/chat/app.rs` - -Состояние, поведение, хелперы жизненного цикла и тесты. Половина модуля с «данными + методами». - -| Из `chat.rs` | Новое местоположение | Видимость | -|---|---|---| -| Строки 33–38 (MessageRole) | `app.rs` | `pub` (сохранена с сегодняшнего дня) | -| Строки 40–46 (ChatMessage) | `app.rs` | `pub` (сохранена) | -| Строки 48–54 (AgentInfo) | `app.rs` | `pub` (сохранена) | -| Строки 56–60 (InputMode) | `app.rs` | приватный `enum` (сохранён) | -| Строки 62–69 (SlashCommandResult) | `app.rs` | приватный `enum` (сохранён) | -| Строки 71–85 (struct App) | `app.rs` | `pub(super)` — был приватным к модулю в chat.rs; теперь должен пересекать новую файловую границу в `render.rs` и `events.rs` | -| Строка 86 (SPINNER_FRAMES) | `app.rs` | `pub(super)` (используется и `App::tick`, и `render_status_bar`) | -| Строки 88–457 (impl App) | `app.rs` | без изменений | -| Строки 459–471 (discover_agents) | `app.rs` | `pub(super)` (вызывается `run_chat` в `mod.rs`) | -| Строки 990–992 (timestamp_now) | `app.rs` | `pub(super)` не нужен — единственные вызывающие находятся в самом `app.rs`. Оставить приватным. | -| Строки 994–1002 (truncate_str) | `app.rs` | то же — вызывается только `App::simulate_agent_response`. Оставить приватным. | -| Строки 1004–1111 (mod tests) | `app.rs` (после отбрасывания стража) | `#[cfg(test)] mod tests` | - -**Заметка о видимости.** Чистое перемещение кода сохраняет наблюдаемое поведение. Но элементы `App`, `SPINNER_FRAMES`, `discover_agents`, `render_ui`, `run_event_loop`, и типы `MessageRole`/`ChatMessage`/`AgentInfo`, которые ранее были приватными к модулю (или только crate-pub, но неиспользуемыми), теперь должны иметь видимость, подходящую для пересечения новой границы подмодуля. Новая видимость — самая узкая из работающих: - -- Элементы, потребляемые только внутри `app.rs`: остаются приватными (timestamp_now, truncate_str, InputMode, SlashCommandResult). -- Элементы, потребляемые между `app.rs`/`render.rs`/`events.rs`: `pub(super)` (App, SPINNER_FRAMES, MessageRole, AgentInfo, discover_agents). -- Элементы, потребляемые `mod.rs`: `pub(super)` (run_event_loop в events.rs, render_ui в render.rs, App + discover_agents). -- Ранее `pub` типы `MessageRole`, `ChatMessage`, `AgentInfo`: это единственный спорный момент. Сегодня они `pub` на уровне крейта (видны как `chat::MessageRole` и т.д.). Цель Подхода A «сохранить видимость» гласит, что они должны оставаться видимыми на уровне крейта после перемещения. **Решение:** объявить их `pub` внутри `app.rs` и реэкспортировать через `pub use app::{MessageRole, ChatMessage, AgentInfo};` в `tui/chat/mod.rs`. Видимый из крейта путь остаётся коротким (`tui::chat::ChatMessage` вместо `tui::chat::app::ChatMessage`), совпадая с сегодняшней поверхностью с точностью до префикса `tui::`. - -### `tui/chat/render.rs` - -Все 7 функций render и потребитель SPINNER_FRAMES. Чистый код представления. - -| Из `chat.rs` | Новое местоположение | Видимость | -|---|---|---| -| Строки 473–510 (render_ui) | `render.rs` | `pub(super)` (вызывается `events.rs` через `run_event_loop`) | -| Строки 512–538 (render_status_bar) | `render.rs` | приватная `fn` (сохранена) | -| Строки 540–636 (render_messages) | `render.rs` | приватная `fn` | -| Строки 638–672 (render_input) | `render.rs` | приватная `fn` | -| Строки 674–700 (render_hint_bar) | `render.rs` | приватная `fn` | -| Строки 702–779 (render_help_overlay) | `render.rs` | приватная `fn` | -| Строки 781–838 (render_agent_select) | `render.rs` | приватная `fn` | - -Необходимые импорты: -```rust -use ratatui::{ - Frame, - layout::{Alignment, Constraint, Layout, Margin, Rect}, - style::{Color, Style}, - text::{Line, Span}, - widgets::{Block, Borders, Clear, List, ListItem, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, Wrap}, -}; -use crate::theme::{self, AGENT_LABEL, DIM, HINT_KEY, PRIMARY, PRIMARY_STRONG, SURFACE, SURFACE_STRONG, USER_LABEL}; -use super::app::{App, AgentInfo, InputMode, MessageRole, SPINNER_FRAMES}; -``` - -### `tui/chat/events.rs` - -Цикл событий. - -| Из `chat.rs` | Новое местоположение | Видимость | -|---|---|---| -| Строки 863–988 (run_event_loop) | `events.rs` | `pub(super)` (вызывается из `run_chat` в `mod.rs`) | - -Необходимые импорты: -```rust -use std::io::Stdout; -use std::time::{Duration, Instant}; -use anyhow::Result; -use crossterm::event::{self, Event, KeyCode, KeyModifiers}; -use ratatui::{Terminal, backend::CrosstermBackend}; -use super::app::{App, SlashCommandResult}; -use super::render::render_ui; -``` - -## Вид публичного API извне модуля chat - -После разделения единственным видимым из крейта элементом является `tui::chat::run_chat` (и реэкспортированные типы `MessageRole`, `ChatMessage`, `AgentInfo`, которые остаются `pub` согласно цели сохранения видимости Подхода A). `main.rs` ссылается ровно на один из них: - -```rust -// crates/coven-cli/src/main.rs строка 150 (до): -Some(Command::Chat) => chat::run_chat(), - -// после: -Some(Command::Chat) => tui::chat::run_chat(), -``` - -И объявление `mod` в строке 23 (после Фазы 1): - -```rust -// до: -mod chat; - -// после: -mod tui; -``` - -Алфавитная позиция объявления `mod` смещается с `mod chat;` (между `mod api;` и `mod control_plane;`) на `mod tui;` (между `mod theme;` и `mod verification;`). - -## Тесты - -### Миграция - -Все пять существующих тестов/хелперов (`app_with_agents`, `agent`, плюс 4 поведенческих теста, нацеленных на методы `App`) переезжают в блок `#[cfg(test)] mod tests` файла `app.rs` без изменений. - -Тест-страж `chat_module_stays_single_file_to_avoid_rust_module_ambiguity` (chat.rs:1036) **удаляется**. Его цель состояла в том, чтобы предотвратить именно то разделение, которое реализует эта спецификация. Требуемый им импорт `use std::path::Path;` удаляется вместе с ним. - -### Без заменяющего стража - -Сам компилятор Rust отклоняет единственный по-настоящему неоднозначный случай (одновременное существование `src/tui/chat.rs` и `src/tui/chat/mod.rs`). Тест, утверждающий «эти конкретные файлы существуют в такой раскладке», был бы ограничением, поддерживаемым через каждую будущую реструктуризацию без функциональной выгоды. - -## Критерии приёмки - -Фаза 2 завершена, когда: - -1. `crates/coven-cli/src/chat.rs` больше не существует (`git ls-files` ничего по нему не возвращает; в рабочем дереве такого файла нет). -2. `crates/coven-cli/src/tui/mod.rs` существует с единственным содержимым `pub mod chat;` (плюс комментарий документации уровня модуля). -3. `crates/coven-cli/src/tui/chat/` содержит ровно четыре файла: `mod.rs`, `app.rs`, `render.rs`, `events.rs`. Никаких других. -4. `crates/coven-cli/src/main.rs` имеет `mod tui;` (алфавитная позиция скорректирована) и `tui::chat::run_chat()` в строке 150. -5. `cargo build -p coven-cli` успешен с нулём предупреждений. -6. `cargo test -p coven-cli` проходит; счётчик модульных тестов уменьшается ровно на один (удалённый тест-страж). Smoke-тесты проходят в количестве 4. -7. `cargo clippy -p coven-cli --no-deps` выдаёт ноль предупреждений. -8. Ни один элемент модуля chat не получает новой экспозиции за пределами `tui::chat::run_chat`, `tui::chat::ChatMessage`, `tui::chat::AgentInfo`, `tui::chat::MessageRole` (три реэкспортированных типа из сегодняшней поверхности). -9. Ручная проверка: запуск `coven chat` открывает TUI и отрисовывает её без видимых регрессий (те же цвета, та же раскладка, те же сочетания клавиш). - -## Оценочный масштаб diff - -| Файл | Действие | Строки | -|---|---|---| -| `crates/coven-cli/src/chat.rs` | Удалить | -1111 | -| `crates/coven-cli/src/tui/mod.rs` | Создать | ~10 | -| `crates/coven-cli/src/tui/chat/mod.rs` | Создать | ~40 | -| `crates/coven-cli/src/tui/chat/app.rs` | Создать | ~530 | -| `crates/coven-cli/src/tui/chat/render.rs` | Создать | ~380 | -| `crates/coven-cli/src/tui/chat/events.rs` | Создать | ~150 | -| `crates/coven-cli/src/main.rs` | Правка в 1 строку + 1 замена mod | ±2 | - -Итого: ~0 строк (файл реорганизуется, а не сокращается). Удалённый тест-страж убирает ~25 строк из текущего итога.