@jmanuelcorral/bond-app
v0.1.4
Published
Local orchestrator and hub-container runner for multi-agent tickets
Readme
bond-app
Orquestador local de runs en hub-contenedores Docker, con herdr-app como interfaz (ver el plan en bond-hub/docs/plans/; decisión D19).
- Backend: el orquestador (
npm start), solo en loopback, con la API local de D13 (token por instalación en~/.bond-app/token, fichero 0600). - Frontend: herdr-app con el layout
bondy sus mods.bond-boardes el tablero de tickets con 5 columnas de ancho fijo (Ready,Running,Waiting,Finished,Error): lanzar y cancelar runs, selección de tarjeta para enfocar la consola inferior de herdr-app con la sesión activa (terminal.show), crear tickets con historia enlazada (GitHub issue), diálogo de borrado con comprobación de integración de rama remota, contadores y filtros.bond-settingses el panel plegable de Ajustes (credenciales de agentes, GitHub y «Rebuild»).bond-titlebares la barra de título propia: logo de bond, botones Agentes y Ajustes, arrastrable, con minimizar, maximizar y cerrar en Linux y Windows.bond-statuses la barra de estado: API, GitHub, versiones y runs activos. Todo vive enapp/y se instala con un comando. - Identidad visual (P6): temas
bond-lightybond-darksacados de la guía de estilo de la web, y el logo rediseñado en SVG (app/brand/). El mapeo de tokens, las diferencias con la web y lo que no se puede cambiar están enapp/brand/TOKENS.md. Para retocar colores se editanapp/themes/*.json(y su fila en TOKENS.md) y se ejecutanpm run app:install. - Sesión del run: cada contenedor lleva herdr-core (
hc); al arrancar el run, el orquestador lo registra como máquina de hc (bond-<run>) pordocker exec, sin SSH ni puertos publicados, y arranca el agente en una terminal de hc comorunner. Pulsar la tarjeta abre esa terminal en herdr-app (terminal.peek). Al terminar, cancelar o reconciliar el run, la máquina se borra con el contenedor y su red.
GitHub (D20): en Ajustes, «Usar mi sesión de gh» guarda en el orquestador el token de
gh auth token (base SQLite 0600, como las credenciales de agentes; la API solo dice si
hay credencial y su login). Lanzar un run no pide token: usa ese, que llega al contenedor
por stdin. Sin credencial, el lanzamiento se rechaza y el diálogo lo dice. Si gh no tiene
sesión, «Iniciar sesión» abre una pestaña con gh auth login --web.
Fin del run y entrega (P7): el run pasa de running a Finished cuando el agente
termina con código 0, o por entrega explícita. El contenedor Docker y la sesión de herdr
permanecen vivos. La entrega (crear PR) ya no es automática: el usuario la solicita a través
del agente (o con el botón «Entregar…» en la tarjeta). El agente corre bond-app pr dentro
del contenedor (sin parámetros y sin token de GitHub), que pide la entrega al orquestador a
través del socket local /var/run/bond-app/bond-app.sock. La entrega:
- Verifica con los
verify_commandsdel ticket (array de comandos de shell que se ejecutan comorunneren el clon). Si uno falla bajo el límite (por defecto 3), el run vuelve a Running y el agente recibe el comando y su salida para reintentar; al alcanzar el límite consecutivo, pasa a Waiting (verification_failed) esperando la intervención del usuario (nudge/desbloqueo). - Commit de lo que dejó el agente en
feat/<ticket>(sin hooks). - Push solo de la rama del ticket al repo del ticket: lo hace el orquestador, no el
agente. El token (D20) entra por stdin de un
docker execcomo root que empuja desde un repo limpio (sin hooks ni configuración que el agente pueda haber escrito); el agente nunca lo tiene. Cualquier otro repo o rama se rechaza antes de ejecutar nada. - PR con la API REST de GitHub desde el host (token solo en la cabecera), con el
resumen del ticket; evento
run.pr_opened.
Borrado de tarjeta (P7): cada tarjeta dispone de un botón «Borrar…» en todos sus estados
(DELETE /api/v1/tickets/:id o /runs/:id, que borra el ticket completo y todos sus runs
asociados). Al pulsarlo se abre un diálogo de confirmación que detiene y elimina el contenedor
Docker, la red, la máquina en herdr-core y los worktrees locales. En estado Finished, antes de
borrar la rama remota feat/<ticket>, el orquestador comprueba contra GitHub si dicha rama
ya fue integrada (merged) en la rama base (main); si no está integrada, la UI advierte al
usuario y requiere pulsar «Borrar igualmente» para forzar la eliminación remota.
Correspondencia entre estados del run y columnas del tablero (P7)
El tablero de bond-board organiza las tarjetas en cinco columnas de ancho fijo. Cada estado interno del run (RunState) mapea a una columna:
| Columna en el tablero | Estados del run (RunState) | Descripción en el flujo de trabajo |
|---|---|---|
| Ready | ready, queued, analyzing | Ticket recién creado, encolado para arranque o en proceso de registro y análisis del hub. |
| Running | running, verifying | Ejecución activa de los agentes en el contenedor o verificación en curso de los verify_commands. |
| Waiting | waiting, blocked | Algún agente espera respuesta del usuario (waiting), o el run está bloqueado (blocked: hub incompleto, límite de fallos de verificación, error en registro de issue). |
| Finished | finished, pr_ready | El agente o equipo terminó su trabajo con éxito (o entrega realizada). El usuario puede inspeccionar la consola, pedir la entrega (bond-app pr) o borrar la tarjeta. |
| Error | failed | Error irrecuperable (fallo de contenedor, timeout, presupuesto agotado, salida anómala del agente o fallo en push/PR). |
Hub en cada run (P5): un ticket trabaja sobre un solo repo (repo_url, el flujo de
P4), sobre una lista de repos (repos: [{url, base_branch?, agent?}]; con dos o más, el
run crea un hub con bond hub init/add) o sobre un hub que ya existe
(hub_url, hub_base y, opcional, repo_agents: {repo: agente}). Los tickets
antiguos se leen como lista de uno. En un run con hub:
Montaje: se clona el hub (o se crea) en
/workspace/huby cada repo de suhub.tomlcon la credencial de GitHub, un clon cada vez y siempre por stdin (D8). Un submódulo se monta moviendo su clon a su ruta; un enlace, con un.bond/hub.local.tomlpropio del contenedor que apunta a su clon.Análisis (estado
analyzing, eventohub.analysis): comprobaciones fijas (bond hub sync --yesybond hub check; repos sinurl, fuera de github.com o que el token no puede leer; bases que no existen; agentes del equipo que no están en la imagen; el checkagentesdebond hub checkcuenta solo si nombra el agente del equipo en ese repo) y después un agente de hub (el pi del ticket en modo-p, solo con herramientas de lectura, con un HOME desechable que solo tiene su propia credencial: las del equipo entran en el contenedor después del análisis) que lee la historia,AGENTS.mdydocs/y dice qué repos faltan, o que falta algo sin lo que la historia no se puede hacer. Con huecos, el run pasa a Blocked (hub_incomplete) sin lanzar ningún agente de repo, y la tarjeta enseña el análisis. «Aprobar arreglos…» (POST /runs/:id/hub/approve) aplica los que tienen arreglo (urlde un repo que no la tenía, si el token puede leergithub.com/<dueño del hub>/<repo>;bond hub addde un repo que falta) en la rama del run del hub, los commitea allí y vuelve a analizar. El agente de hub corre con--no-approve(ignora el.pidel hub, que aún no es de confianza).BOND_APP_ANALYSIS_COMMANDsustituye el agente de hub (array JSON; el prompt va al final) uofflo quita. «Desbloquear…» en ese estado manda instrucciones al agente de hub, reintenta montar lo que falte y vuelve a analizar (también cuando ningún hueco tenía arreglo automático).Equipo: con el hub completo, la terminal de hc del run abre herdr (su TUI) y en ella
bond team feat/<ticket> --yes: un worktree y un agente por repo. El agente de cada repo es el que le da el ticket (o el del ticket): el run lo pone comodefault_agenten el.bond/bond.tomlde ese repo solo en disco, mientras se abre el equipo, y después lo deja como estaba. Solo valen agentes que la imagen trae (BOND_APP_IMAGE_AGENTS, hoypi); otro se rechaza al crear el ticket. Reciben el prompt del ticket (bond team prompt). «Abrir sesión» en la tarjeta enseña esa sesión de herdr con los paneles de los agentes. La imagen trae la config de herdr sin el asistente de primer arranque y pi confía en/workspacey en los worktrees, para que nada se quede esperando una pregunta.Entrega por repo («Entregar…»): en cada repo con la rama del run, verificación en su worktree, commit de lo que dejó su agente y push de
feat/<ticket>con las garantías de P4 (root sobre el sha exacto, base real de GitHub, guarda de.github/workflows, solo los repos del run y solo esa rama), y su PR; después el hub, si tiene remoto y su rama del run añade commits (p. ej. los arreglos aprobados). Los commits de config de bond (bond init en un repo) son cambios y se entregan. El estado de cada repo queda en el run (repo_states): si uno falla, el run pasa a Blocked nombrándolo, y un reintento no vuelve a empujar ni a abrir PR en los ya entregados. El ticket pasa a PR Ready solo cuando todos los repos con cambios tienen su PR. La tarjeta enseña cada repo con su PR. «Desbloquear…» en un run con hub bloqueado por la entrega manda el mensaje a todo el equipo (bond team prompt).
Si el push o el PR fallan, el run pasa a Blocked con el motivo. En una tarjeta Blocked,
«Desbloquear…» manda un mensaje al agente (se escribe en su terminal, o abre otra con el
mensaje si el agente ya salió) y el run vuelve a Running (POST /runs/:id/nudge).
Si el core de hc del host se reinicia y pierde la máquina de un run vivo, la pasada
periódica la vuelve a registrar y la sesión se abre de nuevo (M-1).
Supone una máquina de un solo usuario (D18): no hay usuarios múltiples en el host. Cualquier proceso local que lea el fichero del token o llegue a loopback puede usar la API; si bond-app pasara a un host multiusuario, esto y D13 deben revisarse antes.
Versiones
- herdr-app 0.1.12 o posterior y hc 0.1.17 o posterior en el host (las comprueba
npm run app:install; la barra de estado las muestra). - La imagen del runner (
runner/Dockerfile, etiquetabond-app-runner:p5) fija hc 0.1.17 y herdr 0.9.3 con su sha256, bond y pi; sigue sin sshd ni puertos. Para otra versión de hc, «Rebuild» acepta{"hc": "<versión>", "hc_sha256": "<sha256>"}(dehttps://releases.herdr.dev/core/<versión>/manifest.json), y para herdr{"herdr": "v<versión>", "herdr_sha256": "<sha256>"}; versión y checksum van juntos. - herdr-app y hc están en 0.1.x: tras cada actualización,
npm run app:install -- --check.
Arrancar y CLI bond-app
bond-app se distribuye como paquete npm público (@jmanuelcorral/bond-app) con el binario bond-app. Se puede instalar directamente desde npm, desde el repo o empaquetarlo localmente:
npm install -g @jmanuelcorral/bond-app
# O desde un paquete local:
npm pack
npm install -g ./jmanuelcorral-bond-app-0.1.2.tgzPublicar en npm
La publicación va por staged publishing desde GitHub Actions (.github/workflows/release.yml), al subir un tag vX.Y.Z. Procedimiento:
- Subir
versionenpackage.json(una versión publicada no se puede sobrescribir) y commitear. - Etiquetar y subir el tag:
git tag vX.Y.Z && git push origin vX.Y.Z. El workflow comprueba que el tag coincide conpackage.json, pasa typecheck y tests unitarios, crea la release de GitHub con el.tgzadjunto y deja ese mismo.tgzen el staging de npm (npm stage publish). Autentifica con el secretNPM_TOKENsi está definido; si no, por OIDC (trusted publishing: hay que dar de alta el repo y el workflow en npmjs.com → el paquete → Trusted Publishing). - Aprobar el staged package con 2FA: el workflow imprime el stage-id en el resumen del job;
npm stage approve <stage-id>o npmjs.com → pestaña Staged Packages → Approve. Hasta aprobarlo, la versión no es pública.
--provenance (attestations SLSA) solo se pasa mientras el repo es público: sigstore rechaza repos fuente privados (Unsupported GitHub Actions source repository visibility: "private"). Con el repo privado el workflow publica sin procedencia y lo anuncia en el log; si el repo se hace público, las attestations vuelven solas.
Antes de publicar se puede comprobar el contenido: npm pack --dry-run. No deben aparecer los ficheros generados de los mods (gpui-kit.d.ts, jsconfig.json); están excluidos con patrones ! en files. Si el .npmrc de una máquina apunta el scope a otro registro (p. ej. @jmanuelcorral:registry=https://npm.pkg.github.com), al instalar hay que sobrescribirlo: npm install -g @jmanuelcorral/bond-app --@jmanuelcorral:registry=https://registry.npmjs.org/.
Comandos del binario bond-app
bond-app start [opciones]— Arranca el orquestador en primer plano.- Directorio de datos por defecto:
~/.bond-app(o$BOND_APP_DATA_DIR). - Opciones:
--port <puerto>(defecto 3000),--host <ip>(defecto 127.0.0.1, solo loopback por D13),--data-dir <directorio>. - Parada limpia: al recibir
SIGINT(Ctrl+C) oSIGTERM, cierra el servidor HTTP, detiene temporizadores y elimina sockets de runs activos saliendo con código 0.
- Directorio de datos por defecto:
bond-app install [opciones]— Instala el layoutbond, los mods y los temas en herdr-app (~/.config/herdr-app).- Opciones:
--home <dir>($HERDR_APP_HOME),--api <url>,--token-file <ruta>,--check,--skip-version-check,--force,--launcher,--remove-launcher.
- Opciones:
bond-app open [opciones]— Abre herdr-app (si no está arrancado) y cambia al layoutbond(herdr-app do layout.switch --name bond).- Opciones:
--home <dir>($HERDR_APP_HOME),--timeout <ms>(defecto 10000).
- Opciones:
bond-app status [opciones]— Consulta el estado del orquestador y la integración con herdr-app.- Opciones:
--port <puerto>,--host <ip>,--data-dir <dir>,--home <dir>,--json. - Código de salida: 0 si el orquestador está corriendo (o si se invoca con
--json), 1 si está parado.
- Opciones:
bond-app --version(-v,version) — Muestra la versión (0.1.2).bond-app --help(-h,help) — Muestra la ayuda de uso.
Arranque desde bond (bond app)
Al ejecutar bond app (o bond sin subcomando cuando default_command = "app", D21):
- Comprueba si
bond-appestá en elPATH(si no, explica cómo instalarlo). - Ejecuta
bond-app installpara asegurar que el layout, los mods y los temas están al día. - Ejecuta
bond-app openpara abrir herdr-app con el layoutbond. - Ejecuta
bond-app starten primer plano en la terminal (Ctrl+C para limpiamente el orquestador).
Uso directo desde el repositorio
npm ci --ignore-scripts
DOCKER_BUILDKIT=0 docker build -t bond-app-runner:p5 runner/ # o «Rebuild» desde ajustes
npm start # orquestador en 127.0.0.1:3000 (node bin/bond-app.js start)
node bin/bond-app.js install -- --check # layout, mods y temas en ~/.config/herdr-app
node bin/bond-app.js install -- --check --launcher # además, el lanzador «bond» (opcional)
node bin/bond-app.js open # abre herdr-app con el layout bond
node bin/bond-app.js status # estado del orquestadorDespués, en herdr-app: ctrl-shift-l hasta el layout «bond» (o
herdr-app do layout.switch --name bond). El instalador no toca la ventana abierta, ni
sobrescribe mods o layouts que no instaló él. Opciones: --home <dir> (o
HERDR_APP_HOME), --api <url> (loopback), --token-file <ruta> (por defecto
$BOND_APP_DATA_DIR/token o ~/.bond-app/token), --force (sustituir un bond.json o un
tema bond-*.json editado). Los temas se instalan en themes/ del home de herdr-app y el
logo en mods/bond-titlebar/brand/; sin tocar temas que no instaló él.
Lanzador «bond» (opcional)
--launcher añade al menú del escritorio un lanzador «bond» con el icono de bond, en el
directorio de datos XDG ($XDG_DATA_HOME, si no ~/.local/share):
applications/bond-app.desktop, icons/hicolor/scalable/apps/bond-app.svg y
bond-app/bond-launch. Este último abre herdr-app, o usa la ventana abierta, y muestra el
layout bond. No toca herdr-app.desktop ni su icono, ni pisa un lanzador que no sea suyo.
npm run app:install -- --remove-launcher lo quita.
Lo que no se puede cambiar sin tocar ficheros de herdr-app: el icono de la ventana abierta y
de su entrada en la barra de tareas. El escritorio los asocia por la clase de la ventana
(herdr-app) con herdr-app.desktop (Icon=herdr-app), así que, aunque se abra desde
«bond», la ventana sigue llevando el icono de herdr-app. Tampoco se pueden cambiar las
pantallas propias de herdr-app (bienvenida, ajustes, novedades), que no son mods del layout.
Dentro de la ventana, nada de lo que dibuja el layout bond usa el logo de herdr.
BOND_APP_AGENT_COMMAND (array JSON, p. ej. '["bash"]') sustituye el agente del ticket
en la terminal del run: sirve para probar sin un agente de pago.
Comprobaciones
npm run typecheck— tipos (orquestador, tests e instalador)npm test— unitariasnpm run test:ui— frontend de herdr-app sin ventana: modelo del tablero,herdr-app checkde cada mod y vista, layout, contraste AA de los temas, TOKENS.md frente a los temas, e instalador (con lanzador) contra unHERDR_APP_HOMEy unXDG_DATA_HOMEtemporalesnpm run test:integration— con Docker y hc reales (sesión de hc propia en/tmp/bhc-*, nunca la del usuario); necesita la imagenbond-app-runner:p5- Entrega de extremo a extremo (P4):
BOND_APP_E2E_SANDBOX=<owner>/<repo privado de prueba> npm run test:integration. Empuja ramas y abre PRs en ese repo con la sesión deghdel host, y al terminar cierra los PRs y borra las ramas. Usa pi con el proveedor propiollamaswap(0 USD) si está en~/.pi/agent/models.json. Nunca contra un repo real. - Hub de extremo a extremo (P5):
BOND_APP_E2E_HUB=<owner>/<hub privado de prueba> npm run test:integration. El hub de prueba lleva enhub.tomllos repos privadosbond-app-sandbox-2(submódulo) ybond-app-sandbox-3(enlace con url), del mismo dueño; el criterio 3 con agente nombrabond-app-sandbox. Monta un hub existente, crea uno desde una lista y bloquea uno incompleto hasta «Aprobar arreglos», con pi enllamaswap(0 USD). Solo empuja una rama temporal del hub, que borra al acabar.
