# WebSocket (/docs/referencia/websocket)

HQ Fabric abre dos WebSocket. OpenAPI no sabe describir sus mensajes, así que van aquí. El del navegador,
`/api/ws`, lleva los eventos del workspace y las terminales en vivo. El del daemon, `/api/daemon/ws`, lleva las
órdenes del servidor a un runtime y la salida de sus terminales. Las dos rutas también están en la [referencia
de la API](/docs/referencia/api), con su autenticación.

## El sobre [#el-sobre]

Los dos sockets mandan frames de texto, cada uno con un objeto JSON. La forma es la misma en los dos sentidos.

| Campo | Tipo | Uso |
|---|---|---|
| `type` | string | El tipo del mensaje. Siempre está. |
| `session_id` | string | La sesión de terminal. Se omite si va vacío. |
| `task_id` | string (uuid) | La tarea. Se omite si va vacío. |
| `data` | string (base64) | Bytes de la terminal. Se omite si va vacío. |
| `cols`, `rows` | integer | Tamaño de la terminal. Se omiten si valen 0. |
| `payload` | JSON | El contenido de un evento o de una orden. Se omite si va vacío. |

Los eventos del workspace traen sólo `type` y `payload`. Los mensajes de terminal usan los demás campos. Un frame
que no es JSON, o que trae un `type` desconocido, se ignora sin respuesta.

## `/api/ws`: el navegador [#apiws-el-navegador]

### Conexión [#conexión]

Abres `/api/ws?token=<token>&workspace=<slug>`. El navegador no puede poner cabeceras en un WebSocket, así que
el token viaja en la URL; con otro cliente puedes mandarlo en `Authorization: Bearer <token>`. Vale la sesión del
navegador o un token personal `hqf_` con alcance «api». El token de alcance «runtime», el que guarda `hqf setup` en
la máquina del daemon, no vale aquí.

- Sin token válido, la respuesta es 401 `unauthorized`.
- Con un token de alcance «runtime», es 403 `token_scope`.
- Si no eres miembro del workspace, o falta `workspace`, es 404 `workspace_not_found`.
- Si llega un `Origin`, tiene que ser uno de `FRONTEND_ORIGIN`, en cualquier modo. Si no, 403 `origin_not_allowed`.
  Un origen de loopback cuenta como el configurado si sólo cambia el nombre (`localhost`, `127.0.0.1`, `[::1]`) y
  mantiene el esquema y el puerto. Que el `Origin` sea igual al `Host` no basta, y `*` no abre este canal.

La membresía se comprueba al conectar. Nada más aceptar, el servidor manda `hello`.

### Límites y keepalive [#límites-y-keepalive]

- Cada mensaje del cliente puede ocupar hasta 1 MiB.
- El servidor manda un ping de WebSocket (un frame de control, no JSON) cada 25 s. Si un ping o una escritura
  tardan más de 10 s, cierra.
- La cola de salida guarda 512 mensajes por cliente. Si se llena, el servidor cierra con el código 1008.
- La web también manda `{"type":"ping"}` cada 25 s, y el servidor responde `pong`.

### Suscripciones [#suscripciones]

Los eventos no tienen canales. El servidor decide a quién manda cada uno: a todo el workspace, a una lista de
personas (casi siempre quien ve el issue) o a una sola persona. Las terminales sí se piden una a una con
`term.subscribe`, y sólo recibes `term.output` y `term.closed` de las sesiones a las que te suscribiste. Al
desconectarte las pierdes todas.

### Del navegador al servidor [#del-navegador-al-servidor]

| Tipo | Campos | Cuándo y qué pasa |
|---|---|---|
| `term.subscribe` | `session_id` (string) | Quieres ver una terminal en vivo. Si la sesión existe y no puedes verla, responde `term.missing`. Un shell sólo lo ve el dueño de su runtime; la sesión de un agente, quien ve el issue de su tarea. Después `Subscribe` exige que la sesión sea de tu workspace; si no lo es, o si no existe, `term.missing`. Si todo va bien, responde `term.replay` con el búfer. Una sesión cerrada se puede seguir pidiendo durante 30 min. |
| `term.unsubscribe` | `session_id` (string) | Dejas de ver la terminal. No hay respuesta. |
| `term.input` · `term.resize` · `term.close` | `session_id` (string); `data` (string, base64 de lo tecleado) en `term.input`; `cols` y `rows` (integer) en `term.resize` | Tecleas, cambias el tamaño o cierras una terminal. Sólo si la sesión existe, es de tu workspace y eres el **dueño del runtime** (`isRuntimeOwner`), también en la sesión de un agente. Si no, se ignora sin respuesta. Si pasa, se reenvía tal cual al daemon del runtime: mismo `type`, `session_id`, `data`, `cols` y `rows`. |
| `ping` | ninguno | Keepalive del cliente (la web lo manda cada 25 s). Responde `pong`. |

### Del servidor al navegador: respuestas y terminales [#del-servidor-al-navegador-respuestas-y-terminales]

| Tipo | Campos | Cuándo | Destinatarios |
|---|---|---|---|
| `hello` | ninguno | Nada más aceptar la conexión. | — |
| `pong` | ninguno | En respuesta a `ping`. | — |
| `term.replay` | `session_id` (string); `data` | Tras un `term.subscribe` aceptado. | — |
| `term.missing` | `session_id` (string) | Un `term.subscribe` a una sesión que no existe, no es de tu workspace o no puedes ver. También cuando cambia la audiencia de un issue (al borrar un proyecto o cambiar roles, el asignado o quién es miembro) y dejas de ver la sesión de agente a la que estabas suscrito: `recheckWatchers` te da de baja y te lo avisa. | — |
| `term.output` | `session_id` (string); `data` (string, base64) | El daemon manda salida de la terminal (su `term.output`). En una sesión de agente, la salida se redacta por líneas antes de guardarla y mandarla, así que puede llegar más tarde o en otros trozos. Al cerrarse la sesión se manda lo que quedaba en el redactor. | Los suscritos a la sesión. |
| `term.closed` | `session_id` (string); `payload.exit_code` (integer) | Se cierra la sesión. `exit_code` es el que manda el daemon en su `term.closed`, o `-1` si el daemon lleva 30 s desconectado o si no se pudo pedir el shell al daemon. | Los suscritos a la sesión. |

### Del servidor al navegador: eventos del workspace [#del-servidor-al-navegador-eventos-del-workspace]

«Quien ve el issue» son los miembros que cumplen la audiencia del issue: sus roles en el proyecto, si es el
asignado o participante, y si el issue es `high` o está marcado.

| Tipo | Campos | Cuándo | Destinatarios |
|---|---|---|---|
| `term.sessions` | `{opened: string}` (id de la sesión) **o** `{closed: string}` | El daemon anuncia una terminal (`term.open`), alguien abre un shell desde la web (`POST /api/w/{ws}/terminals`) o se cierra una sesión. | La sesión de un agente con tarea: quien ve el issue de la tarea. Un shell o una sesión sin tarea: todo el workspace. |
| `issue.updated` | el issue entero: el struct `Issue`, el mismo que devuelve `GET /api/w/{ws}/issues/{num}` | Se crea un issue (también un subissue que crea un agente) o cambia: lo modifica una persona, termina una tarea, cambia su SDLC, sus artefactos, sus huecos o su PR… `issueUpdated` tiene unas 30 llamadas. | Quien ve el issue (después del cambio). |
| `issue.deleted` | `id` (string, uuid); `number` (integer) | Se borra un issue. | Quien lo veía antes del borrado. |
| `comment.created` | `issue_number` (integer); `comment`. En el comentario que deja una conducción en vivo (`task.steer`) **sólo** va `issue_number`, sin `comment`. | Se crea un comentario en un issue. | Quien ve el issue. |
| `activity` | el struct `Activity`: `id`, `issue_id`, `issue_key`, `issue_title`, `actor_type`, `actor_id`, `actor_name`, `actor_color`, `kind`, `payload` (JSON), `created_at` | Cada vez que se guarda una actividad. | Con issue: quien ve el issue (`issue.audience_narrowed`, sólo los admins de entre ellos). `content.blocked`: la audiencia del proyecto. Con `task_id` en el payload: quien ve el issue de esa tarea. Sin nada de eso: todo el workspace (`Broadcast`). Los extra de O3 que no ven el issue (dueño del runtime y delegados) la reciben con `issue_title` a null. |
| `task.updated` | la tarea entera: el struct `Task`, el de `GET /api/w/{ws}/tasks/{tid}` | Cualquier cambio de una tarea (`broadcastTask`, con más de 50 llamadas: encolar, reclamar, empezar, completar, cancelar, aprobar, publicar, esperas, preguntas, permisos…). | Quien ve el issue de la tarea. |
| `task.events` | `task_id` (string); `issue_number` (integer); `events` (array de `{seq: integer, kind: string, payload: JSON, created_at: date-time}`) | El daemon sube eventos de la tarea (`POST /api/daemon/tasks/{tid}/events`). No incluye los de `kind` = `pty` ni los que la redacción descarta; los payloads ya van redactados (L3). | Quien ve el issue. |
| `task.subagents` | `task_id` (string); `issue_number` (integer) | Entre los eventos subidos hay uno de `kind` = `subagents` (cambió el árbol de subagentes). | Quien ve el issue. |
| `task.wait` | `task_id` (string); `issue_number` (integer); `wait_state` (string o null; no va en todos) | Cambia el subestado de espera. Lo informa el daemon (`wait_state` = el nuevo, o null si sale de la espera), una solicitud de permiso nueva o decidida (sin `wait_state`), una espera por cuota (`quota`) o una tarea interactiva que espera entrada (`input`). | Quien ve el issue. |
| `task.checkpoint` | `task_id` (string); `issue_id` (string, uuid). Ojo: aquí va el id del issue, no `issue_number`. | El agente guarda un checkpoint (`POST /api/daemon/tasks/{tid}/checkpoint`). Sin el texto. | Quien ve el issue. |
| `task.context` | `task_id` (string); `issue_number` (integer) | El daemon informa del medidor de contexto en vivo y la fila se actualiza (como mucho una vez por intervalo, `contextMetricsEvery`). | Quien ve el issue. |
| `task.steered` | `task_id` (string); `issue_number` (integer) | Alguien conduce la tarea en vivo (`deliverSteer`). Sin el texto. | Quien ve el issue. |
| `session.hibernated` | `task_id` (string); `issue_number` (integer) | El daemon pasa la tarea a la espera `hibernated` (antes no lo estaba). | Quien ve el issue. |
| `session.resumed` | `task_id` (string); `issue_number` (integer) | Se concede reanudar una sesión al reclamar su continuación (`sessionResumable`), o alguien despierta una sesión hibernada (`POST /api/w/{ws}/sessions/{tid}/resume`). | Quien ve el issue. |
| `question.asked` | `question_id` (string); `task_id` (string); `issue_number` (integer) | El agente hace una pregunta estructurada (`POST /api/daemon/tasks/{tid}/questions`, una pregunta por llamada). | Quien ve el issue. |
| `question.answered` | `question_id` (string); `task_id` (string); `issue_number` (integer) | Se cierra una pregunta (`afterQuestionClosed`). | Quien ve el issue. |
| `permission.requested` · `permission.decided` | `request_id` (string); `task_id` (string); `issue_number` (integer); `status` (string, el estado de la solicitud) | Una tarea supervised pide un permiso nuevo, o se decide, expira o se cancela (`permBroadcast`). | Quien ve el issue. Si la solicitud es de ejecución en el host (`host_exec`), también el dueño del runtime y quien puede decidirla, aunque no vean el issue (SEC-139). |
| `diff_comment.updated` | `task_id` (string); `comment` | Se crea un comentario en el diff de una tarea. **[duda]** Sólo lo emite la creación; no vi que modificar o borrar un comentario del diff lo emitan. | Quien ve el issue. |
| `inbox.item` | `kind` (string), `id` (string) y, según `kind`, `task_id` (string), `issue_key` (string) y `category` (string). Variantes en la tabla de abajo. | Entra algo en la bandeja «Necesita de ti» de una persona. Sólo ids, nunca el texto. | — |
| `inbox.resolved` | `kind` (string, los mismos de `inbox.item`); `id` (string) | Algo sale de la bandeja: la sesión deja de esperar entrada, se descarta un aviso, se decide un permiso, se cierra una pregunta o un hueco, se amplía el tope de tiempo. | — |
| `context.updated` | Uno de estos: `{node_id: string}` (nodo creado o modificado), `{deleted: string}` (nodo borrado), `{edge_id: string}` (arista creada), `{deleted_edge: string}` (arista borrada), `{lifecycle: integer}` (transiciones del ciclo de vida), `{curated: true}` (el curador aplicó lecciones de una tarea, o `hqf agent remember`) | Cambia la Malla de Contexto. | Nodo: quien lo ve. Arista: quien ve sus dos nodos. `lifecycle` y `curated`: todo el workspace, sin ids. |
| `project.updated` | el struct `Project` | Se crea o se modifica un proyecto. | Todo el workspace (`Broadcast`). |
| `agent.updated` | el struct `Agent` | Se crea o se modifica un agente. | Todo el workspace. |
| `agent.deleted` | `id` (string) | Se borra un agente. | Todo el workspace. |
| `runtime.updated` | Tres formas: (a) el struct `Runtime` entero, con `live`, `host_error` y `outdated` calculados al momento; (b) `{id: string, status: "offline", live: false}`; (c) `{id: string}` | (a) El daemon se conecta o se desconecta del socket, un heartbeat tras estar offline o con otros proveedores, cambios de configuración, host o registro (`broadcastRuntimeCtx`). (b) El barrido marca offline un runtime sin daemon conectado. (c) `broadcastRuntimeOwnerAdmins` (O4, cuota). | (a) y (b): todo el workspace. (c): el dueño del runtime y los admins y owners del workspace. |
| `runtime.deleted` | `id` (string) | Se borra un runtime (`DELETE /api/w/{ws}/runtimes/{rid}`). No confundir con el `runtime.deleted` que va al daemon (§2.2). | Todo el workspace. |
| `runtime.consent_requested` | `runtime_id` (string) | Una tarea pide un consentimiento del dueño para `worktree.yaml`. | Sólo el dueño del runtime. |
| `runtime.teardown_pending` | `runtime_id` (string) | Un teardown de worktree no corrió (va con un `inbox.item` de `kind` `teardown`). | Sólo el dueño del runtime. |

**Variantes de `inbox.item`**

| `kind` | Campos | `category` | Destinatarios |
|---|---|---|---|
| `protected_conflict` | `id` (aviso), `task_id`, `issue_key` | `approvals` | la audiencia del aviso que ve el issue |
| `input` | `id` (= tarea), `task_id`, `issue_key` | `questions` | quien lanzó la sesión, si ve el issue |
| `quota_notice` | `id` (aviso) | `quota` | el dueño del runtime |
| `permission` | `id` (solicitud), `task_id`, `issue_key` | `permissions` | quien puede decidirla (`permDeciders`) |
| `question` | `id` (pregunta), `task_id`, `issue_key` | `questions` | quien puede responder y ve el issue |
| `wall_time` | `id` (= tarea), `task_id`, `issue_key` | `gates` | `wallTimeAudience` |
| `question` o `gap` | `id`, `task_id` (puede ir vacío) | `questions` | la persona que se añade a quién responde, si ve el issue |
| `gap` | `id` (hueco), `task_id`, `issue_key` | `questions` | la lista fijada que ve el issue |
| `teardown` | `id` (aviso) | `teardown` | el dueño del runtime |

## `/api/daemon/ws`: el daemon [#apidaemonws-el-daemon]

### Conexión [#conexión-1]

El daemon `hqf` lo abre con el token de su runtime (`hqfrt_`) en `Authorization: Bearer`; también vale
`?token=`. Sin un token de runtime que exista, la respuesta es 401. El token de una tarea (`hqftk_`) no sirve y
recibe 403 `task_scope`. El handshake no mira el `Origin`: los daemons no son navegadores. Sí mira el `Host`, como
todas las rutas (ver [Configuración](/docs/referencia/configuracion#qué-nombres-atiende-el-servidor)).

Al conectar, el runtime pasa a `online`, los navegadores reciben `runtime.updated` y el servidor manda
`task.available`. El daemon vuelve a anunciar sus terminales con `term.open`. Si ya había una conexión del mismo
runtime, la anterior se cierra.

Cada mensaje puede ocupar hasta 8 MiB, con el mismo keepalive y la misma cola que el navegador. Si el daemon se
desconecta y no vuelve en 30 s, sus terminales se cierran con `exit_code` -1. Para reconectar espera 1, 2, 4, 8,
16 y después 32 s.

No hay suscripciones: el servidor manda a un runtime concreto o, para `task.available`, a todos los daemons del
workspace. Si el runtime no está conectado, varias rutas de la API responden 409 `runtime_offline`.

### Del daemon al servidor [#del-daemon-al-servidor]

| Tipo | Campos | Cuándo y qué pasa |
|---|---|---|
| `term.open` | `session_id` (string); `task_id` (string, puede ir vacío); `payload.kind` (string, `agent` o `shell`; vacío cuenta como `agent`); `payload.title` (string) | El daemon abre una terminal (shell o sesión interactiva de agente), o las vuelve a anunciar al reconectar. Registra la sesión (`OpenSession`). Si ya existía una sesión `shell` con ese id, sigue siendo `shell`. Las sesiones de agente se redactan. Manda `term.sessions` `{opened}` a los navegadores. |
| `term.output` | `session_id` (string); `data` (string, base64) | Sale algo por la terminal. Si `data` no es base64 válido, se ignora. |
| `term.closed` | `session_id` (string); `payload.exit_code` (integer) | Termina la terminal, o no se pudo abrir (`-1`). |
| `runtime.config.result` | `payload`: `request_id` (string); `ok` (boolean); `error` (string, si falló); `config` (`RuntimeConfig`: `name`, `max_parallel`, `task_timeout`, `repos` (objeto proyecto → ruta), `repos_dir`, `worktrees_dir`, `config_path`, `env_keys` (sólo nombres) y `providers` si se pidió `detect`); `repo` (`{path, remote?, branch?}`, si se vinculó un repo) | Respuesta a un `runtime.config`. El servidor la entrega a quien espera ese `request_id` sólo si viene del runtime al que se preguntó. |
| `heartbeat` | ninguno | **[duda]** El servidor lo acepta (actualiza `last_seen_at` y `status='online'`), pero el daemon del repo no lo manda por el socket: su heartbeat va por HTTP a `POST /api/daemon/heartbeat`. |

### Del servidor al daemon [#del-servidor-al-daemon]

| Tipo | Campos | Cuándo y qué pasa |
|---|---|---|
| `task.available` | ninguno | Al conectar, y cuando puede haber trabajo: se encola una tarea, una tarea termina o se aprueba (puede liberar WIP). El daemon intenta reclamar enseguida (`poke`), sin esperar al siguiente sondeo de 15 s. |
| `task.cancel` | `task_id` (string) | Alguien cancela la tarea (`POST /api/w/{ws}/tasks/{tid}/cancel`) o se pasa de su tope de tiempo total. El daemon marca la ejecución como cancelada, deniega lo que esté esperando un permiso y la para. |
| `task.discard` | `task_id` (string) | Se descartan las demás tareas de un fan-out al aprobar una, o el PR de la tarea ya se integró en GitHub. El daemon corre el teardown, quita el worktree y borra la rama local. |
| `task.steer` | `task_id` (string); `payload.steer_id` (string) | Alguien conduce la tarea en vivo. El texto no viaja por el socket: el daemon lo pide con `GET /api/daemon/tasks/{tid}/steers/{sid}`, lo escribe en la sesión y confirma con `POST …/delivered`. |
| `sessions.purge` | `payload`: `task_ids` (array de string); `worktrees` (array de string); `items` (array de `{task_id: string, worktree: string}`) | Se cerró o se borró el issue: hay que borrar los transcripts de sus sesiones. Se reenvía hasta que el daemon confirma. |
| `session.resume` | `task_id` (string) | Quien lanzó la sesión, o el dueño del runtime, despierta una sesión hibernada. |
| `task.merge` | `task_id` (string); `payload`: `expect_sha` (string, el commit aprobado), `restricted` (boolean), `branch` (string), `base` (string, se omite si no hay o es `HEAD`) | Se aprueba una tarea de un proyecto **sin** GitHub con token: integración local. El daemon responde por HTTP a `POST /api/daemon/tasks/{tid}/merged`. |
| `task.push` | `task_id` (string); `payload`: `url` (string), `token` (string, token de empuje recién emitido; falta si no se pudo emitir), `revoke_url` (string), `expect_sha` (string, si hay commit exacto). En un issue high o marcado (`pushPayloadFor`) también: `mode` (`confirmed` o `follow`), `manifest_hash`, `repo_id` (integer), `base`, `pr_title`, `pr_body`, `check`, `restricted` (true), `branch` y, en `follow`, `confirmed_repo_url`, `confirmed_base` y `confirmed_repo_id` (integer) | Se aprueba, publica o reintenta una tarea de un proyecto en GitHub, o se pide el PR automático al completar. El daemon empuja, revoca el token al terminar y responde por HTTP a `POST /api/daemon/tasks/{tid}/pushed`. |
| `task.manifest` | `task_id` (string); `payload`: `url`, `token`, `revoke_url`, `repo_id` (integer), `branch`, `base`, `sha`, `pr_title`, `pr_body`, `check`, `request_id` (string, 24 caracteres hexadecimales) | Antes de empujar una tarea de un issue high o marcado: el servidor pide al daemon el manifiesto de lo que saldría a GitHub. El daemon responde por HTTP a `POST /api/daemon/tasks/{tid}/manifest` con `request_id` y `manifest` o `error`. |
| `artifact.write` | `task_id` (string); `payload`: `writes` (array de `{id, op, path, content, message, author_name, author_email}`, todos string; `op` es `edit` o `approve`), `restricted` (boolean) y `push` (opcional: `{url, token, expires_at?, revoke_url?, ref, hidden_ref, only_paths}`) | Hay commits humanos de artefactos pendientes en un issue (editar o aprobar desde la web) y ninguna jugada del issue está en curso. |
| `shell.open` | `session_id` (string, uuid que genera el servidor); `task_id` (string, puede ir vacío); `cols`, `rows` (integer); `payload`: `cols`, `rows` (integer), `input` (string, el atajo inicial), `title` (string) | El dueño del runtime abre una terminal desde la web (`POST /api/w/{ws}/terminals`). El daemon abre el shell en el worktree de la tarea (o en su repo, o en el home), escribe `input` a los 700 ms y anuncia la sesión con `term.open`. |
| `runtime.config` | `payload`: `request_id` (string, uuid) y, según la petición, `name` (string), `max_parallel` (integer), `task_timeout` (string), `link` (`{project: slug, path: string}`), `unlink` (array de string), `detect` (boolean), `env_set` (objeto variable → API key), `env_unset` (array de string). Una petición vacía (`{request_id}`) sólo lee la configuración. | El dueño cambia o consulta la configuración del runtime desde la web (nombre, paralelismo, timeout, repos vinculados, CLIs y API keys). El servidor espera la respuesta `runtime.config.result` hasta 15 s. |
| `runtime.deleted` | ninguno | Se borra el runtime desde la web. El daemon borra el id y el token del runtime de su `config.json` y para el worker de ese workspace. |
| `term.input` · `term.resize` · `term.close` | `session_id` (string); `data` (string, base64) en `term.input`; `cols`, `rows` (integer) en `term.resize` | El dueño del runtime teclea, cambia el tamaño o cierra la terminal en la web (§1.1). El daemon escribe los bytes en el PTY, lo redimensiona o cierra la sesión. Si la sesión no existe en el daemon, lo ignora. |