La interfaz web de chat

Un cliente de chat de navegador completo - barra lateral, streaming, aprobaciones, almacén SQLite.

La interfaz web de chat

Una entrada gateways/*.bx con exposes: "webui" envía un cliente de chat de navegador completo para el agente - una barra lateral de conversación, streaming con razonamiento y llamadas de tool, aprobaciones human-in-the-loop, temática por visitante, y un almacén SQLite real detrás.

Vive bajo gateways/ porque ahí es donde se declaran las exposiciones, pero es un subsistema por derecho propio, que es por lo que tiene su propia página.

// gateways/chat.bx
class {
	function configure() {
		return {
			exposes     : "webui",
			path        : "/chat",
			apiKeyEnvVar: "CHAT_UI_API_KEY"   // opcional - ver Asegurando la API
		};
	}
}

Eso genera un <path>/index.html estático (servido directamente - no se necesita ruta) más una API dedicada bajo <path>/api, respaldada por un handlers/ChatUi.bx y models/ChatDb.bx generados.

La interfaz es HTML/CSS/JS vainilla sin dependencias - sin Bootstrap, AlpineJS ni un paso de build de Vite - y está preconstruida y empaquetada dentro de BX Agents mismo: bxAgents build nunca ejecuta npm install/npm run build, y un proyecto generado nunca necesita Node ni npm instalados en absoluto. Todo lo que la página necesita está incrustado en el único index.html generado.

Esa restricción es sobre el build, no sobre el alcance. La página es un cliente completo: barra lateral de conversación, streaming con razonamiento y llamadas de tool, aprobaciones, compactación, temática del lado del servidor. Lo que realmente todavía falta se lista bajo What is not here yet.

La página habla con su propia ruta <path>/api generada vía POST <path>/api/stream (Accept: text/event-stream), usando fetch() + un lector manual de ReadableStream - no el EventSource del navegador, que no puede hacer POST ni configurar cabeceras personalizadas, ambas necesarias aquí.

event: chunk
data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"Ray","reasoning":"...","tool_calls":[...]}}]}

event: done
data: [DONE]

Porque llega el envelope completo, el razonamiento y las llamadas de tool ya están en el cable sin necesidad de un endpoint extra: delta.reasoning (normalizado a través de cada proveedor por bx-ai) se renderiza como una franja colapsada de "Pensando", y delta.tool_calls como chips colapsados por llamada. Los argumentos de llamada de tool se transmiten como fragmentos JSON parciales indexados por index, así que la página acumula por índice en lugar de asumir que cualquier chunk único contiene una llamada completa.

Cómo se ve realmente un turno de streaming

sequenceDiagram
    autonumber
    participant B as navegador (index.html generado)
    participant H as handlers/ChatUi.bx
    participant A as el agente
    participant D as models/ChatDb.bx (SQLite)

    B->>H: POST /chat/api/stream, Accept: text/event-stream
    H->>D: resuelve la conversación para esta sesión
    H->>A: agent.stream( ... )
    H-->>B: event: thread - el threadId, enviado ANTES del primer chunk
    loop por cada chunk que emite bx-ai
        A-->>H: un envelope normalizado completo de bx-ai
        H-->>B: event: chunk - choices[0].delta.content / .reasoning / .tool_calls
    end
    H->>D: persiste el turno
    H-->>B: event: done - [DONE]

El evento thread va primero porque una cabecera de respuesta no puede leerse antes de que el cuerpo empiece a llegar, y la página necesita ese threadId para poder hacer POST /cancel a mitad de turno.

La API generada

Una entrada webui monta veinte acciones bajo <path>/api, servidas por un handlers/ChatUi.bx generado:

Cada una está delimitada por el getUserSessionIdentifier() de ColdBox como el userId. Las primeras tres mantienen la forma y el formato de cable exactos de toAi().

threadId es autoritativo del servidor: tomado del request cuando se suministra, acuñado de lo contrario, y siempre reflejado de vuelta - como una cabecera de respuesta X-Thread-Id en /invoke y /batch, y como un evento SSE thread enviado antes del primer chunk en /stream (una cabecera no puede leerse antes de que el cuerpo empiece a llegar). Ese es el mismo contrato que adoptó el propio toAi() de ColdBox 8.1, así que un cliente escrito contra uno funciona contra el otro.

/clear y /compact ambos tienen cuidado con el scope. /clear pasa por el propio clear( userId, conversationId ) de cada memoria en lugar de AiAgent.clearMemory(), que no toma argumentos y borraría el historial de cada visitante; /compact pasa por summarize( config, userId, conversationId ) por la misma razón. La compactación reemplaza los mensajes más antiguos de esta conversación con un resumen escrito por IA y mantiene los pocos más recientes, sin tocar nada fuera del par (userId, conversationId) del llamador.

// Agent.bx - lo que hace funcional a /compact
memory: {
	type            : "cache",
	summaryProvider : "openai",
	summaryModel    : "gpt-4o-mini",
	summaryThreshold: 10
}

Usuarios e inicio de sesión

Por defecto la interfaz web no tiene cuentas ni compuerta — está abierta, y cada visitante es anónimo. Esa es la experiencia de cero ceremonia de bxAgents serve, y no es una postura de despliegue. Declarar users en una entrada webui activa una compuerta real de inicio de sesión respaldada por cbauth y el mismo almacén SQLite que usa todo lo demás.

Sin cuentas, la interfaz es un espacio de trabajo compartido

No hay identidad por visitante, a propósito. Cada visitante a una interfaz web sin cuentas lee y escribe las mismas conversaciones, preferencias y memoria de agente — quien pueda alcanzar la página ve todo en ella.

Ese es el punto de ejecutar sin cuentas en lugar de un descuido: una interfaz abierta es una única herramienta compartida (un laptop, una máquina interna de confianza), no un servicio multi-tenant. Darle a cada navegador su propia porción solo fragmentaría un espacio de trabajo en copias por navegador que nadie pidió, y cualquier id del lado del cliente que hiciera la fragmentación sería falsificable de todos modos.

// gateways/chatUi.bx
users : [
    { username: "ada",   passwordEnvVar: "ACME_ADA_PASSWORD", displayName: "Ada Lovelace" },
    { username: "grace", passwordHash: "pbkdf2$210000$...",   displayName: "Grace Hopper" }
]

Las contraseñas nunca se escriben en configuración

Una cuenta nombra la variable de entorno que contiene su contraseña (passwordEnvVar), o lleva un valor ya hasheado (passwordHash). Una clave password literal es un error de build, no una advertencia — ignorarla silenciosamente te dejaría creyendo que habías configurado una contraseña cuando solo habías commiteado una.

Un passwordHash es seguro de commitear precisamente porque no puede revertirse. Genera uno con el mismo hasher que usa la app:

bxAgents hash-password --password="correct horse battery staple"

Qué cambia el inicio de sesión

Todo lo delimitado por usuario se re-indexa a la cuenta real. El handlers/ChatUi.bx generado resuelve la identidad desde cbauth directamente, en un método (resolveUserId()), y la memoria del agente, el índice de conversaciones, las preferencias y la propiedad de ejecuciones pendientes todas se indexan por su valor de retorno.

Lee cbauth en lugar del ajuste identifierProvider de ColdBox deliberadamente: un closure declarado en el struct de configuración coldbox nunca llega a configSettings — verificado en un arranque real, tanto en la forma literal documentada como como asignación posterior — así que cualquier cosa que dependiera de ese ajuste estaba silenciosamente obteniendo un id de sesión en su lugar.

La diferencia práctica: las conversaciones y preferencias siguen a la persona a través de navegadores y dispositivos, y limpiar cookies ya no crea un "usuario" completamente nuevo.

Ciclo de vida

Las cuentas se reconcilian desde la configuración en cada arranque, en este orden: el interceptor de esquema migra, el seeder escribe cuentas, luego la compuerta de inicio de sesión empieza a aplicarse.

• Añadir un usuario a la configuración lo crea.
• Cambiar su contraseña la actualiza. El seeder rehashea solo cuando la contraseña configurada ya no coincide con lo almacenado, así que una contraseña sin cambios cuesta una verificación en lugar de un hash nuevo.
• Eliminarlo de la configuración desactiva la cuenta en lugar de eliminarla. Sus conversaciones referencian su id, así que eliminar la fila huerfanaría ese historial en lugar de revocar el acceso. Ya no pueden iniciar sesión; sus datos permanecen intactos y regresan si la cuenta se restaura.
• Un passwordEnvVar cuya variable está sin configurar omite esa cuenta por completo y registra una advertencia en webui-auth. Esto falla cerrado a propósito — crear la cuenta con una contraseña vacía sería mucho peor que que no existiera.

Qué no es esto

Esto es un roster fijo de cuentas provisionadas por el operador, no un sistema de gestión de usuarios. No hay auto-registro, ni restablecimiento de contraseña, ni roles o permisos, ni límite de tasa o de gasto por usuario. Si necesitas identidad federada en su lugar, edita resolveUserId() en el handler generado para devolver tu propio principal autenticado — el resto de la interfaz web ni sabe ni le importa de dónde vino el id.

Human-in-the-loop

Cuando el agente se pausa para aprobación, el stream emite un chunk middleware_stop que no lleva detalle. La página por lo tanto pregunta a GET /pending?threadId= qué se está solicitando, lo renderiza con Aprobar / Rechazar, y responde vía POST /resume - que transmite la continuación del mismo turno, así que el resultado aterriza en la conversación en lugar de comenzar una nueva.

decidedBy se rellena desde la sesión del lado del servidor, nunca desde el cuerpo del request: quién aprobó algo es exactamente el tipo de afirmación que un llamador no debería poder hacer sobre sí mismo.

Historial y recarga

El transcript vive en el DOM; la conversación vive en la memoria del agente. Sin rehidratación una recarga muestra una pantalla vacía mientras el agente sigue recordando todo - así que la página se vería en blanco y luego respondería preguntas de seguimiento sobre mensajes que el usuario no puede ver. Al cargar, la página por lo tanto llama a GET <path>/api/history y reproduce los mensajes almacenados (markdown y todo), recayendo en el mensaje de bienvenida cuando la conversación está vacía o el fetch falla.

New inicia un conversationId nuevo. No elimina nada - la conversación previa permanece en el servidor bajo su propio id y aparece en la barra lateral, que es para lo que existe la tabla de conversaciones.

Lo que hace la página

La página enviada es un cliente de chat real, no una carcasa de demostración. Lee GET /info primero y se moldea a lo que el servidor realmente reporta, así que un control solo aparece donde existe la capacidad.

La recuperación importa más de lo que suena. La última conversación abierta se recuerda en localStorage, pero las conversaciones mismas viven en el servidor. Si ese id ya no existe — eliminado en otra pestaña, o un almacén nuevo — la página recae en la conversación restante más reciente en lugar de rehidratar hacia una pantalla vacía sin fila activa.

Las pantallas estrechas obtienen un layout real en lugar de uno exprimido: bajo 40rem la barra lateral se superpone al transcript en lugar de robarle su ancho, y se honra prefers-reduced-motion.

El almacén SQLite

Cada proyecto webui obtiene una base de datos SQLite. No es opcional y no hay ningún flag para desactivarlo.

La razón es un vacío real, no una preferencia: el IAiMemory de bx-ai no tiene ninguna API de enumeración. Es un bucket por (userId, conversationId) — puedes leer, escribir y limpiar uno, pero nada en él responde "qué conversaciones tiene este usuario." Una lista de conversaciones, preferencias por usuario, y cualquier otra cosa relacional necesita almacenamiento real junto a la memoria, no dentro de ella.

El datasource se registra en Application.bx y la gramática se fija en config/ColdBox.bx:

// Application.bx (generado)
this.datasources[ "bxagents" ] = {
	"driver"  : "sqlite",
	"database": expandPath( "./data/chat.db" )
}
this.datasource = "bxagents"   // NO this.defaultDatasource - ver abajo

// config/ColdBox.bx (generado)
qb : {
	defaultGrammar : "SQLiteGrammar@qb",
	defaultOptions : { datasource : "bxagents" }
}

Ambos son opcionales de sobreescribir, por entrada:

Un database.path absoluto falla el build: se resuelve con expandPath() dentro de la app generada, así que una ruta absoluta escapa silenciosamente del directorio de la app y rompe un despliegue de .bxa empaquetado.

El esquema está versionado y es solo-hacia-adelante. ChatDb.migrate() registra lo que ha aplicado en una tabla bxagents_schema_version y solo aplica lo que es más nuevo, así que arrancar contra un almacén existente es un no-op. v1 crea conversations y preferences. Evolúcionalo añadiendo un nuevo applyV<n>() y aumentando SCHEMA_VERSION — nunca editando una migración que ya se envió, porque SQLite no puede modificar ni eliminar una columna y el propio SQLiteGrammar de qb lanza UnsupportedOperation en lugar de fingir lo contrario.

La gramática es la única pieza específica de SQLite. Todo lo demás pasa por qb, así que apuntar esto a Postgres o MySQL después es un cambio de gramática y datasource en lugar de una reescritura.

Conversaciones y preferencias

Estas son para lo que existe el almacén SQLite, y ambas están delimitadas por el mismo userId derivado del servidor que todo lo demás.

Conversaciones. Cada turno a través de /invoke, /stream o /batch se registra a sí mismo contra el índice: la fila se crea en el primer uso, updatedAt se mueve, y el primer mensaje de usuario se convierte en el título (colapsado a una línea, truncado a 60 caracteres) a menos que ya haya uno configurado — así que un renombrado nunca se deshace silenciosamente por el siguiente turno. messageCount es un contador de visualización, incrementado en dos por turno; un turno que muere a mitad de camino puede dejarlo uno más alto, y /clear lo reinicia. La propia memoria del agente sigue siendo la autoridad sobre lo que realmente se dijo.

/conversations/delete elimina la fila de índice y limpia los mensajes del agente para esa conversación. Eliminar solo la fila dejaría la conversación invisible mientras aún se sienta en el contexto del modelo en el momento en que alguien reutilizara el id.

Preferencias. Del lado del servidor en lugar de localStorage, así que siguen a la identidad en lugar del navegador. Apunta identifierProvider a un principal autenticado real y las preferencias de un visitante lo siguen a través de dispositivos sin cambio al código generado.

Branding y temática

Cada clave de abajo es opcional - la entrada funciona con solo exposes y path.

theme se mapea directamente sobre las propiedades personalizadas de CSS de la página: accent, accentFg, bg, fg, muted, border, surface, inputBg, bubbleUser, bubbleUserFg, bubbleAssistant, bubbleAssistantFg, bubbleError, reasoningFg, reasoningBg, toolFg, toolBg, radius, radiusSm, font, fontMono, fontSize, maxWidth. Un bloque anidado theme.dark sobreescribe cualquiera de los mismos tokens para el modo oscuro. Un token desconocido falla el build en lugar de ser silenciosamente ignorado, así que un typo sale a la superficie de inmediato en lugar de dejarte preguntándote por qué tu color de marca nunca apareció.

// gateways/chat.bx
theme: {
	accent : "0f766e",
	radius : "10px",
	font   : "Inter, system-ui, sans-serif",
	dark   : { accent : "rgb(45, 212, 191)" }
}

Para cualquier cosa que los tokens no cubran - fuentes personalizadas, layout, reglas por elemento - coloca un resources/webui/theme.css en el proyecto. Se incrusta al final en el <style> de la página, así que le gana tanto a los valores por defecto enviados como a los tokens de theme; y siendo un archivo .css real, el hex #rrggbb ordinario funciona ahí normalmente. (Un </style literal en ese archivo falla el build, ya que terminaría prematuramente el bloque de estilo de la página.)

Identidad de conversación: la sesión ES el identificador de usuario

Cada memoria que un agente mantiene está indexada por (userId, conversationId) - y un agente puede mantener varias a la vez (memories de AiAgent es un array; loadMemoryMessages() itera sobre todas ellas con el mismo par). AiAgent.run()/.stream() recaen en "" para ambos cuando nada los suministra, así que sin identidad del lado del servidor cada visitante aterriza en un único bucket compartido, sin importar qué tipos de memoria estén configurados.

La solución es identidad, no tipo de memoria. Un proyecto con una exposición webui por lo tanto obtiene:

1. Gestión de sesión activada en el Application.bx generado - this.sessionManagement = true, this.setClientCookies = true, un sessionTimeout de 60 minutos. Las cookies son fundamentales: sin cookie, sin id de sesión.
2. Su propio handlers/ChatUi.bx, que pasa el getUserSessionIdentifier() de ColdBox como el userId del agente en las tres formas de ejecutor - invoke, stream y batch.

// handlers/ChatUi.bx (generado)
private string function resolveUserId() {
	return controller.getUserSessionIdentifier()
}

Delegar a ColdBox en lugar de leer session.sessionId directamente compra tres cosas: el id está prefijado por aplicación, cae de vuelta a través de URLToken/CFID si una sesión de alguna manera no está disponible, y - lo que más importa - honra el ajuste de configuración identifierProvider. Apunta eso a tu principal autenticado y cada memoria se re-indexa al usuario real sin cambio al handler generado.

Porque la identidad es emitida por el servidor, el scoping se mantiene sin importar qué memorias configure el proyecto - una o muchas, window, cache, jdbc, vectorial, cualquier mezcla.

conversationId todavía viene del cliente, y eso es deliberado: distingue varias conversaciones pertenecientes al mismo visitante - es lo que rota el botón New. No es el límite de aislamiento; el userId derivado de la sesión lo es.

Ningún tipo de memoria se fuerza. Elige uno (o varios) por agente con una clave memory en Agent.bx, la misma forma que checkpointer:

// Agent.bx
memory: { type: "cache", maxMessages: 50 }

Un proyecto sin webui mantiene las sesiones desactivadas y el propio valor por defecto de memoria de bx-ai - una app solo de API/gateway no tiene navegador que rastrear, y una sesión ahí es overhead más una cookie que nadie pidió.

Renderizado de respuesta

Las respuestas del asistente se renderizan a través de un subconjunto de markdown deliberadamente pequeño: código con fence e inline, negrita/cursiva, enlaces, listas de viñetas y numeradas, encabezados. Se aplica escape-primero: el texto del modelo se escapa a HTML antes de que se introduzca una sola etiqueta, así que ninguna salida del modelo puede convertirse en markup en vivo, y los hrefs de enlace están en lista blanca a http(s)/mailto así que una URL javascript: nunca se convierte en un anchor en absoluto.

What is not here yet

La página está completa contra su propia API - cada ruta que necesita existe y se ejercita. Estos son los vacíos:

Ver Limitaciones conocidas para qué se verificó y qué no contra un arranque real de ColdBox, incluyendo las partes de esta página que solo están cubiertas por aserciones a nivel de generador en lugar de conducir un navegador.