Ir al contenido
HQ Fabric

WebSocket

Los mensajes de los dos WebSocket de HQ Fabric, el del navegador y el del daemon.

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, con su autenticación.

El sobre

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

CampoTipoUso
typestringEl tipo del mensaje. Siempre está.
session_idstringLa sesión de terminal. Se omite si va vacío.
task_idstring (uuid)La tarea. Se omite si va vacío.
datastring (base64)Bytes de la terminal. Se omite si va vacío.
cols, rowsintegerTamaño de la terminal. Se omiten si valen 0.
payloadJSONEl 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

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

  • 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

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

TipoCamposCuándo y qué pasa
term.subscribesession_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.unsubscribesession_id (string)Dejas de ver la terminal. No hay respuesta.
term.input · term.resize · term.closesession_id (string); data (string, base64 de lo tecleado) en term.input; cols y rows (integer) en term.resizeTecleas, 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.
pingningunoKeepalive del cliente (la web lo manda cada 25 s). Responde pong.

Del servidor al navegador: respuestas y terminales

TipoCamposCuándoDestinatarios
helloningunoNada más aceptar la conexión.—
pongningunoEn respuesta a ping.—
term.replaysession_id (string); dataTras un term.subscribe aceptado.—
term.missingsession_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.outputsession_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.closedsession_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

«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.

TipoCamposCuándoDestinatarios
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.updatedel 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.deletedid (string, uuid); number (integer)Se borra un issue.Quien lo veía antes del borrado.
comment.createdissue_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.
activityel struct Activity: id, issue_id, issue_key, issue_title, actor_type, actor_id, actor_name, actor_color, kind, payload (JSON), created_atCada 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.updatedla 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.eventstask_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.subagentstask_id (string); issue_number (integer)Entre los eventos subidos hay uno de kind = subagents (cambió el árbol de subagentes).Quien ve el issue.
task.waittask_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.checkpointtask_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.contexttask_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.steeredtask_id (string); issue_number (integer)Alguien conduce la tarea en vivo (deliverSteer). Sin el texto.Quien ve el issue.
session.hibernatedtask_id (string); issue_number (integer)El daemon pasa la tarea a la espera hibernated (antes no lo estaba).Quien ve el issue.
session.resumedtask_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.askedquestion_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.answeredquestion_id (string); task_id (string); issue_number (integer)Se cierra una pregunta (afterQuestionClosed).Quien ve el issue.
permission.requested · permission.decidedrequest_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.updatedtask_id (string); commentSe 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.itemkind (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.resolvedkind (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.updatedUno 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.updatedel struct ProjectSe crea o se modifica un proyecto.Todo el workspace (Broadcast).
agent.updatedel struct AgentSe crea o se modifica un agente.Todo el workspace.
agent.deletedid (string)Se borra un agente.Todo el workspace.
runtime.updatedTres 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.deletedid (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_requestedruntime_id (string)Una tarea pide un consentimiento del dueño para worktree.yaml.Sólo el dueño del runtime.
runtime.teardown_pendingruntime_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

kindCamposcategoryDestinatarios
protected_conflictid (aviso), task_id, issue_keyapprovalsla audiencia del aviso que ve el issue
inputid (= tarea), task_id, issue_keyquestionsquien lanzó la sesión, si ve el issue
quota_noticeid (aviso)quotael dueño del runtime
permissionid (solicitud), task_id, issue_keypermissionsquien puede decidirla (permDeciders)
questionid (pregunta), task_id, issue_keyquestionsquien puede responder y ve el issue
wall_timeid (= tarea), task_id, issue_keygateswallTimeAudience
question o gapid, task_id (puede ir vacío)questionsla persona que se añade a quién responde, si ve el issue
gapid (hueco), task_id, issue_keyquestionsla lista fijada que ve el issue
teardownid (aviso)teardownel dueño del runtime

/api/daemon/ws: el daemon

Conexión

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).

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

TipoCamposCuándo y qué pasa
term.opensession_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.outputsession_id (string); data (string, base64)Sale algo por la terminal. Si data no es base64 válido, se ignora.
term.closedsession_id (string); payload.exit_code (integer)Termina la terminal, o no se pudo abrir (-1).
runtime.config.resultpayload: 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ó.
heartbeatninguno[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

TipoCamposCuándo y qué pasa
task.availableningunoAl 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.canceltask_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.discardtask_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.steertask_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.purgepayload: 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.resumetask_id (string)Quien lanzó la sesión, o el dueño del runtime, despierta una sesión hibernada.
task.mergetask_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.pushtask_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.manifesttask_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.writetask_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.opensession_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.configpayload: 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.deletedningunoSe 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.closesession_id (string); data (string, base64) en term.input; cols, rows (integer) en term.resizeEl 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.

En esta página