boshu2/usando-gc

Usando GC

Usa Gas City solo cuando el solicitante la seleccione explícitamente. Trátala como un adaptador de ejecución reemplazable, no como un límite de corrección o finalización. El adaptador no puede seleccionar semántica de AgentOps, emitir un veredicto vinculante o convertir la finalización de la fábrica en una prueba de entrega o validación.

Elige la fábrica primero

AgentOps admite tanto Gas City como el Agentic Coding Flywheel como entornos de ejecución de fábrica de software externos. Usa esta habilidad solo para Gas City. Si el solicitante selecciona el Flywheel, cambia a usando-flywheel y su flujo de trabajo nativo en lugar de envolverlo en Gas City.

AgentOps proporciona habilidades y contratos de evidencia a cualquiera de las fábricas. No necesita su propia fórmula o paquete de roles de Gas City. Instala o enlaza las habilidades de AgentOps en el entorno de ejecución del proveedor antes de iniciar los trabajadores; el Alcalde ascendente, el coordinador y los trabajadores pueden entonces descubrir y seleccionar plan, implement, test, validate y otras habilidades de AgentOps normalmente.

Modelo operativo de Gas City 1.4

Gas City 1.4 está centrado en la ejecución. El supervisor sirve al panel de control y las API de sesión/ejecución tipadas y paginadas. Cada ámbito de ciudad o plataforma (rig) que posee un gráfico necesita su propio core.control-dispatcher; ese trabajador determinista avanza las cuentas de control de la fórmula. Los trabajadores agente reclaman trabajo enrutado. La habilidad ascendente gc.mayor es el coordinador guiado; gc.run-operator lanza y supervisa fórmulas.

La ruta normal de AgentOps es:

1. Instalar y fijar el flujo de trabajo gascity ascendente y las importaciones de roles de plataforma.
2. Agregar el proyecto como una plataforma, preparar su entorno de ejecución de mantenedor estándar y hacer que las habilidades de AgentOps sean visibles para sus sesiones de proveedor.
3. Crear un bead de intención fuente propiedad del solicitante y entregar su id al Alcalde, que escribe los beads del flujo de trabajo y envía la fórmula build-basic, de continuación, revisión o implementación ascendente que coincida con los artefactos disponibles.
4. Leer el estado de ejecución, sesión, bead, artefacto y veredicto. La finalización nunca se infiere del chat o del texto del panel.

Prepara y califica una plataforma antes de su primera construcción con la CLI de AgentOps enviada (no se requiere clonación del repositorio):

ao gc prepare --city /ruta/a/la/ciudad --rig /ruta/a/la/plataforma
ao gc check --city /ruta/a/la/ciudad --rig /ruta/a/la/plataforma

El comando verifica los pines exactos del flujo de trabajo y rol oficiales, captura los scripts de validación y esquemas ascendentes sin cambios dentro del entorno de ejecución .gc de la plataforma, instala solo pequeños envoltorios propiedad de AgentOps en las rutas de verificación de la fórmula, selecciona un Python existente que pueda importar PyYAML y enlaza las habilidades de AgentOps en los receptores Codex de la ciudad y la plataforma. Las habilidades provienen del checkout de AgentOps circundante cuando está presente, de lo contrario, desde la raíz de habilidades instalada; pasa --skills-source para fijar un directorio diferente. Nunca modifica el binario de GC, el caché, las fórmulas, los roles o el paquete ascendente. check emite solo comandos de inspección nativos, no escribe archivos de adaptador y falla antes del gasto del modelo cuando ese contrato de tiempo de ejecución falta o se ha desviado.

prepare también presemilla la confianza de Codex para cada directorio de sesión que existe cuando se ejecuta — las raíces de la ciudad y la plataforma, cada hogar de sesión .gc/agents/** y cada raíz del árbol de trabajo de la plataforma — para que una sesión de Codex en uno de esos directorios no se bloquee en el diálogo de confianza interactivo. Ambas capas persistidas se siembran en $CODEX_HOME/config.toml: confianza del espacio de trabajo ([projects."<dir>"] trust_level = "trusted"), sin la cual Codex informa silenciosamente que ese directorio no tiene hooks en absoluto, y confianza por hook ([hooks.state."<hooks.json>:<evento>:<m>:<h>"] trusted_hash = "sha256:..."), que es lo que los .codex/hooks.json por proveedor del paquete de lo contrario solicitarían. Los resúmenes de los hooks se leen de hooks/list de Codex, nunca se recalculan.

La confianza se juzga por el valor, no por la presencia de una tabla. prepare agrega solo entradas que faltan y se niega, nombrando la entrada, cuando existe una pero no confiere confianza — un trust_level = "untrusted" explícito, un hook que Codex informa como cambiado desde que fue confiado, un hook registrado que Codex aún rechaza, o un hook registrado enabled = false (un hook deshabilitado no es un hook de trabajo confiable). Nunca sobrescribe una decisión del operador, y volver a ejecutarlo es un no-op. También falla en lugar de continuar si Codex devuelve una lista de hooks vacía o no reconocida. El almacén de confianza en sí mismo nunca se edita en el lugar: el contenido combinado se analiza primero en memoria, luego se instala con el escritor atómico duradero de la CLI, por lo que ninguna ruta de fallo puede dejar un archivo de configuración de Codex parcialmente escrito.

ao gc check verifica la misma presemilla solo desde el estado local — no ejecuta ningún subproceso de Codex y no escribe nada, derivando cada clave de hook esperada del hooks.json del propio directorio — y nombra el directorio o hook deficiente específico usando la misma regla que prepare siembra.

Dos limitaciones nombradas.

1. check no puede detectar un hash desactualizado. Debido a que nunca pregunta a Codex, un trusted_hash registrado que ya no coincide con el contenido actual del hook se lee como satisfecho y aún muestra el diálogo de confianza en una sesión real. Solo prepare ve eso — Codex informa el hook como cambiado y prepare se niega. Un check verde, por lo tanto, significa "la confianza está registrada", no "la confianza está fresca".
2. Los hogares creados después de prepare no están cubiertos. El descubrimiento es por marcador del sistema de archivos, por lo que la garantía cubre los directorios de sesión que existen en el momento de prepare. Un hogar de sesión que Gas City materializa después aún lleva hooks no confiables en su primer inicio; prepare nombra los agentes configurados que aún no tienen hogar.

La regla operativa que se sigue de ambas: ejecuta prepare, inicia la ciudad, luego ejecuta prepare nuevamente (es idempotente) antes de despachar.

Paquete y registros preferidos

El registro main integrado cataloga los paquetes oficiales. El registro de la comunidad es configuración opcional:

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search lee el caché del registro local; show informa la procedencia de la versión y los comandos de importación exactos. gc import add declara una fuente/versión, y gc import install lo resuelve en packs.lock. Prefiere una versión aceptada exacta para ciudades reproducibles.

AgentOps prefiere el paquete de construcción gascity oficial, la familia de flujo de trabajo visible en la fábrica pública Maintainer City. La referencia aceptada actual es gascity 0.1.6 en el commit 3b3b89f2011e06d84459aa7bea1552382f13930a:

• panel de control: https://factory.gascity.com;
• flujos de trabajo: build-basic, build-from-*, implement, review, de issue y PR;
• roles de plataforma estándar: gc.run-operator, gc.implementation-worker, planificadores, revisores y editor;
• control de fórmula de ámbito local: core.control-dispatcher;
• coordinación guiada: la habilidad ascendente gc.mayor.

Instala el paquete de flujo de trabajo en el ámbito de la ciudad y su paquete de roles hermano en cada plataforma que ejecute trabajo, siguiendo los comandos exactos devueltos por gc pack registry show main:gascity. Mantén el espacio de nombres gc.* estándar; no anides ni renombres los roles detrás de un paquete de AgentOps.

El trabajo entra en la ciudad a través del Alcalde. El solicitante escribe UN bead de intención fuente con criterios de aceptación, luego entrega al Alcalde su id — el Alcalde descompone, escribe los beads del flujo de trabajo y despacha. El solicitante nunca ejecuta gc sling sí mismo; una ejecución lanzada por el operador evita al coordinador que posee los reintentos, redespacho y cuidado para ese flujo de trabajo.

gc bd create "Agrega una bandera --json al comando de exportación"
gc mail send mayor -s "Build ago-XXXX" \
  -m "Descompón y lanza build-basic para el bead ago-XXXX con push=true open_pr=true." --notify

O, en una sesión interactiva del Alcalde:

Usa la habilidad gc.mayor

gc sling directo sigue siendo una herramienta de depuración para una ciudad sin Alcalde vivo; una ejecución iniciada de esa manera no tiene coordinador y el operador hereda su cuidado.

Las habilidades de AgentOps son herramientas disponibles para los agentes de la fábrica, no un reemplazo del flujo de trabajo. Nombra explícitamente una habilidad en el bead o prompt cuando su comportamiento sea requerido. La descomposición ascendente actual no propaga automáticamente una sección de Habilidades Requeridas de forma libre desde el bead fuente propiedad del solicitante a cada elemento de trabajo generado. Inspecciona la descomposición antes de la implementación; pon un nombre de habilidad requerida en el elemento de trabajo real o en el prompt del trabajador cuando su uso sea una condición de aceptación. La presencia de la habilidad y la invocación de la habilidad son hechos diferentes.

Actualizar una ciudad existente a 1.4

Antes de iniciar su orquestador, ejecuta una vez por ciudad:

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS cuando queda un supervisor directo más antiguo
gc start

Luego confirma:

• gc version informa 1.4.0 desde la ruta prevista;
• gc doctor no tiene fallas de bloqueo;
• cada plataforma que posee un gráfico tiene un core.control-dispatcher no suspendido;
• las importaciones y packs.lock se resuelven;
• ao gc check acepta el entorno de ejecución de mantenedor contenido y los enlaces de habilidades de AgentOps;
• en macOS, el LaunchAgent del supervisor se resuelve en el mismo ejecutable que el binario gc seleccionado;
• los marcadores o proxies inversos del panel de control independiente antiguo se eliminan.

Una ciudad registrada obsoleta puede bloquear cada inicio. Repara esa ciudad con gc doctor --fix, o anúlela explícitamente si está intencionalmente retirada.

Retira un antiguo HQ/canary por nombre o ruta registrada exacta, sin detener el supervisor a nivel de máquina necesario para su reemplazo:

gc cities --json
gc stop /ruta/a/la/ciudad-antigua --timeout 45s
gc unregister /ruta/a/la/ciudad-antigua
gc cities --json

unregister falla en lugar de aceptar silenciosamente un objetivo desconocido. Conserva el directorio de la ciudad hasta que su estado de Beads esté respaldado o se confirme que es descartable. Crea el reemplazo a partir de la plantilla ascendente de Gas City, instala sus importaciones fijadas y verifícalo con gc cities --json, gc --city <nueva-ciudad> status, y gc --city <nueva-ciudad> doctor --json.

Orquestando a través del Alcalde: el bucle de tendencia

Después de entregar la intención al Alcalde, el orquestador ejecuta cinco verbos. Cada verbo tiene un propietario; cruzar propietarios es la clase de falla recurrente que esta sección existe para detener.

Verbo	Propietario	Superficie
Monitorear	orquestador	$API/runs/census y $API/runs/<run-id> en una cadencia fija, más gc mail inbox para respuestas del Alcalde. failed > 0 en el censo, una ejecución en failed/canceled, o correo del Alcalde no leído es la señal de acción; todo lo demás es un tick.
Observar	orquestador	Ante una señal de acción, recorre las capas de visibilidad en orden — censo, detalle de ejecución, gráfico de beads, lista de sesiones, verdad del panel — y detente en la primera capa que explique. No empieces en la verdad del panel.
Impulsar	orquestador, una vez	Un bead ready: despacha una vez a su gc.run_target. Un bead enrutado con una sesión activa: gc session wake <run_target> una vez. Un segundo impulso sobre el mismo tema significa que el diagnóstico es incorrecto — envía correo al Alcalde en su lugar.
Redirigir	Alcalde	Los cambios de prioridad, alcance, cancelación o modelo/proveedor viajan por correo con ids de bead/ejecución. El orquestador nunca relanza, edita beads de flujo de trabajo ni parchea una ejecución activa.
Reelaborar	GC primero, luego Alcalde	Los hallazgos de revisión fallidos reingresan a la ejecución a través de su bucle de corrección nativo (review_fix_formula, por defecto fix-loop-base); los reintentos limitados y cerrados son bucles de gc converge. Solo una ejecución TERMINAL failed/canceled — o una ejecución completada cuyo resultado falla en la aceptación del solicitante — se devuelve: envía un correo al Alcalde con el id de la ejecución y la evidencia de falla para redescomposición y relanzamiento.

La reelaboración que el orquestador realiza manualmente (editar el árbol de trabajo de una ejecución fallida, relanzar su fórmula, cerrar sus beads) crea un segundo autor no coordinado para la misma intención; el relanzamiento del Alcalde entonces compite con él.

Protocolo de bloqueo

Primero clasifica el bead.

• Aún ready: despáchalo una vez a su gc.run_target, luego detente e inspecciona.

• Ya enrutado/en progreso: relanzar es un NO-OP. Despierta a su trabajador propietario una vez:

  gc session wake <run_target>
  

Luego captura el panel tmux exacto nombrado por el estado de la sesión y ejecuta gc doctor. Nunca repares una ciudad desde dentro de esa ciudad.

Nunca crees sesiones propiedad del paquete manualmente. gc session new para un agente singleton o escalado (core.control-dispatcher, trabajadores de rol) crea una sesión con ámbito incorrecto que ocupa el nombre canónico en start-pending y bloquea el reconciliador de generar la real — extendiendo exactamente el bloqueo que se está reparando. El ciclo de vida de la sesión pertenece al reconciliador y al escalado por demanda. Cuando la ciudad misma necesita cuidado (un reconciliador bloqueado, sesiones que nunca salen de drenaje, recableado de modelo o proveedor), envía la solicitud al Alcalde:

gc mail send mayor -s "<asunto>" -m "<solicitud con ids de bead>" --notify

El paquete ascendente puede dejar un paso futuro vinculado por afinidad asignado a una sesión que ya ha reconocido el drenaje. Diagnostica esto solo desde fuera de la ciudad:

ao gc recover-affinity --city /ruta/a/la/ciudad --rig /ruta/a/la/plataforma

El valor predeterminado es una ejecución de prueba (dry run). Si cada asignación listada es correcta, repite con --apply. La reparación limitada solo limpia el asignado en un bead de fórmula actualmente ready cuya sesión gc.session_affinity=require ya no está activa. No lanza, reintenta, cierra, reinicia ni selecciona trabajo.

Visibilidad: cuatro capas

1. Estado del supervisor/ejecución — gc dashboard, detalle de ejecución, gc status y gc session list --json. El detalle de ejecución unifica la escalera de etapas, las transcripciones estructuradas, la tasa de tokens y la tasa de quema estimada. Una lista puede aún informar activo mientras un proveedor está atascado.

   El estado de ejecución programático proviene de la API de ejecución tipada del supervisor — los mismos datos que renderiza el panel. gc status imprime la base de la API; ni gc status --json ni ningún otro subcomando de la CLI lleva objetos de ejecución.

   API="http://127.0.0.1:<puerto>/v0/city/<nombre-de-la-ciudad>"
   curl -s "$API/runs/<run-id>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, …}}
   

2. Gráfico de beads — gc bead graph <run-id> muestra el DAG del flujo de trabajo. Inspecciona los beads uno por uno con gc bead show <bead-id>. Un ready que nunca se despacha es una fórmula que espera entrada; un bead running que no avanza es un trabajador que espera en una compuerta.

3. Lista de sesiones — gc session list --json empareja sesiones con beads y trabajadores. Un trabajador que no reclama un bead enrutado significa que el trabajador está atascado en una compuerta de proveedor o en una compuerta de herramienta. El estado del panel del trabajador responde a gc session wake; si no, verifica la conectividad del proveedor dentro de esa sesión.

4. Verdad del panel — la última capa. Un trabajador del que se ha informado que está reposando que no se despierta con gc session wake está atascado en una compuerta de proveedor o de herramienta. El texto de la compuerta es diagnóstico. Nunca cierres el panel ni toques su entrada — el trabajador está ocupado; el texto es un efecto secundario de la compuerta, no la causa.

   gc session logs <session-id>
   gc session export <session-id>
   gc session wake <session-id>
   

   gc session logs extrae el texto del panel desde la última compuerta de la sesión. export captura la transcripción completa. wake envía una señal de nueva línea a una sesión en reposo. Cuando ninguna se mueve, el problema está fuera de GC — modelo, proveedor o red.

   gc session kill <session-id>   # solo cuando la evidencia muestra que el trabajador
                                  # no se reanudará; el Alcalde relanza.
   gc session close <session-id>  # cierra la sesión en GC; el reconciliador
                                  # reabre para el bead si el supervisor
                                  # reporta que el trabajo aún está activo.
   

   kill y close no son herramientas de inspección. Matar una sesión cuyo trabajador se reanudaría descarta su progreso; cerrar una sesión no cierra a su trabajador.

Integración con el flujo de trabajo del Alcalde

El bucle básico del Alcalde:

1. El Alcalde recibe un bead de intención fuente.
2. Descompone: escribe beads de flujo de trabajo, beads de rol y centinela, y un bead de revisión final.
3. Envía el flujo de trabajo al despachador.
4. El despachador enruta beads a los trabajadores.
5. Los trabajadores ejecutan, usando herramientas/habilidades según lo seleccionen.
6. El Alcalde recibe los resultados; si el bead de revisión final falla, el Alcalde relanza.

Las habilidades de AgentOps son invocadas por los trabajadores cuando los beads nombran la habilidad o el trabajador la selecciona del contexto. La presencia de la habilidad y la invocación de la habilidad son diferentes; poner "Usa la habilidad X" en el bead fuente no garantiza que el flujo de trabajo descompuesto herede esa instrucción. Inserta un bead de habilidad requerida explícito en el flujo de trabajo descompuesto para hacerla vinculante.

Cuentas finales (resumen)

• Provee a los agentes de Gas City con conciencia y capacidad de AgentOps.
• No interpretes la finalización de la fábrica como una corrección; el juicio final pertenece al Alcalde.
• Prepara antes de la sesión; despacha a través del Alcalde; monitorea a través del censo.
• Los trabajadores bloqueados se despiertan; los flujos de trabajo bloqueados buscan al Alcalde.
• Las habilidades de AgentOps son herramientas de agente, no automatizadores de flujo de trabajo.