Las herramientas, área por área

Qué hace cada herramienta que puede llamar un agente, agrupadas por el interruptor de capacidad que la anuncia.

Los nombres de las herramientas son identificadores estables en snake_case. Los errores son estructurados y accionables: una llamada fallida devuelve qué salió mal más una pista que nombra la herramienta o el paso que lo arregla, para que un agente se corrija solo en vez de adivinar. Cuando el área Copias de seguridad (gestión) está encendida, el servidor indica además a los agentes que creen una copia de seguridad de la configuración antes de hacer cambios de configuración. Cuál de estas listas ve de verdad un agente es lo que abre cada área.

Connector: lectura

Herramienta Qué hace

connector_browse Lista el árbol configurado con el estado de salud en vivo: Modbus RTU como controlador, línea serie, dispositivo, tag; todos los demás controladores como controlador, dispositivo, tag, con la carpeta de cada dispositivo al lado. Revela los alias de tag (Driver.Folders….Device.Tag) que usan tag_read, tag_write y las expresiones de Logic. Los alias son nulos mientras el servidor integrado está detenido.

tag_read Lee los valores en vivo de un tag por su alias: el valor bruto a nivel de dispositivo, el valor de ingeniería tras la cadena de conversión, la calidad y las dos marcas de tiempo.

Herramienta	Qué hace
`connector_browse`	Lista el árbol configurado con el estado de salud en vivo: Modbus RTU como controlador, línea serie, dispositivo, tag; todos los demás controladores como controlador, dispositivo, tag, con la carpeta de cada dispositivo al lado. Revela los alias de tag (`Driver.Folders….Device.Tag`) que usan `tag_read`, `tag_write` y las expresiones de Logic. Los alias son nulos mientras el servidor integrado está detenido.
`tag_read`	Lee los valores en vivo de un tag por su alias: el valor bruto a nivel de dispositivo, el valor de ingeniería tras la cadena de conversión, la calidad y las dos marcas de tiempo.

Connector: configuración

Herramienta	Qué hace
`driver_capabilities`	Lista todos los controladores que la aplicación puede servir con los campos de conexión que necesita un dispositivo, el modelo de direccionamiento de tags (dirección de texto libre y campos tipados, o solo uno de los dos), el soporte y los parámetros del descubrimiento, los rangos de tiempos y los tipos de valor admitidos. El mapa que lee un agente antes de `device_upsert` o de `tag_upsert`.
`serial_line_list`	Lista todas las líneas serie Modbus RTU guardadas, incluidas las deshabilitadas y las vacías, con su id estable y los valores de tiempo configurados, automáticos y efectivos.
`serial_line_upsert`	Crea una línea Modbus RTU o actualiza una por su id estable. El nombre y el estado de habilitación cambian en cualquier momento; el intervalo mínimo entre transacciones también cambia con la línea habilitada; el puerto serie, la velocidad en baudios, el formato serie y el tiempo de espera de respuesta solo cambian mientras la línea guardada está deshabilitada.
`serial_line_delete`	Elimina una línea por su id estable. Una línea que todavía contiene dispositivos se rechaza salvo que la llamada autorice de forma explícita eliminar todos los dispositivos y todos los tags hijos.
`device_upsert`	Crea o actualiza un dispositivo por controlador más nombre (el controlador es inmutable tras la creación). Solo cambian los parámetros que se le dan; los campos de conexión son propios de cada controlador; mover un dispositivo a una carpeta reescribe todas las referencias a sus direcciones de tag antiguas. El cambio se concilia de inmediato en el servidor en marcha.
`device_delete`	Elimina un dispositivo y todos sus tags; se concilia de inmediato en el servidor en marcha.
`tag_upsert`	Crea o actualiza un tag de un dispositivo. El direccionamiento es propio de cada controlador (dirección de texto libre y campos tipados, o solo uno de los dos); la respuesta repite la dirección de bus ya compuesta y el alias para `tag_read`. Incluye las etapas de lectura no válida (la acción ante NaN y la presentación de un fallo de lectura) en los tags numéricos.
`tag_delete`	Elimina un tag; se concilia de inmediato.

Logic: lectura

Herramienta	Qué hace
`logic_browse`	Recorre el espacio de direcciones enraizado de Logic, el mismo árbol con puntos que lee toda expresión: System, Server, Connector, Variables, Alarms, Process y Assets. Las carpetas del operador son niveles reales de la dirección; los puntos hijos incluyen su valor en vivo y su calidad.
`logic_read`	Lee un punto por su dirección con puntos (por ejemplo `Variables.Setpoint`) y devuelve el valor en vivo y la calidad.

Logic: configuración

Las altas y actualizaciones son parciales (los parámetros omitidos conservan su valor) y todo borrador combinado pasa la misma validación que aplican los editores de Logic; un borrador no válido se rechaza y no queda nada aplicado a medias.

Herramienta	Qué hace
`variable_upsert`	Crea o actualiza una variable: Expresión (una sola expresión JavaScript de solo lectura sobre el espacio de direcciones) o Memoria (un valor escribible y, si se quiere, retentivo). El nombre es la clave y, saneado, la dirección; el parámetro de carpeta la archiva, reescribiendo todas las referencias a la dirección antigua.
`variable_delete`	Elimina una variable por su ruta, con su valor retenido incluido. Los canales vinculados a ella pierden su origen.
`action_upsert`	Crea o actualiza una acción: un bloque de sentencias JavaScript con exactamente dos verbos de escritura, la asignación a una variable de memoria y la escritura de ingeniería en un tag. Se valida de forma estática, nunca se ejecuta al guardar.
`action_delete`	Elimina una acción por su nombre. Los disparadores vinculados a ella quedan inactivos.
`trigger_upsert`	Crea o actualiza un disparador por intervalo: cada `intervalMs` (100 como mínimo) la acción vinculada se lanza en la cola de la lógica; un tick durante una ejecución pendiente se omite. El vínculo con la acción es flojo y por nombre.
`trigger_delete`	Elimina un disparador; la acción vinculada no se toca.
`alarm_upsert`	Crea o actualiza una alarma: una expresión de condición Bool, la prioridad (Crítica, Alta, Media o Baja), los retardos a la activación y a la desactivación, si se exige reconocimiento, y el estilo del aviso. Guardar una condición o unos tiempos cambiados reinicia la máquina de estados en marcha.
`alarm_delete`	Elimina una alarma por su ruta; un aviso activo se cierra antes.
`logic_folder_upsert`	Crea, renombra o rearchiva una carpeta de organización de una sección (Variables de Logic, Alarmas, Acciones, Disparadores; tres niveles como mucho). En Variables de Logic y en Alarmas, la ruta de la carpeta es parte de la dirección, así que los cambios de nombre y los movimientos reescriben todas las expresiones, todos los scripts, todas las condiciones y todos los vínculos de panel de control que hay debajo.
`logic_folder_delete`	Elimina una carpeta. Nada de lo que contenía se destruye: los elementos y las subcarpetas se rearchivan un nivel más arriba y las referencias se reescriben; un choque de nombres en el destino rechaza la eliminación.

Logic: operación

Todas estas viajan por la única cola de la lógica y se anotan en el diario con el origen MCP.

Herramienta	Qué hace
`variable_write`	Escribe un valor en una variable de Memoria (convertido a su tipo de salida, y retenido cuando es retentiva). Las variables de expresión se calculan y rechazan las escrituras.
`tag_write`	Escribe un valor de ingeniería en un tag con escritura: se deshace por la cadena de conversión del tag, se convierte al tipo del dispositivo y se escribe en el equipo. Los tags de solo lectura y los controladores de solo lectura se rechazan con el motivo.
`action_run`	Ejecuta una acción en la cola de la lógica y devuelve su resultado y su duración. Una acción deshabilitada falla sin llegar a ejecutarse.
`alarm_ack`	Reconoce una alarma, la respuesta del operador; no hace nada cuando no hay nada pendiente.
`alarm_ack_all`	Reconoce todas las alarmas que esperan una respuesta, como un solo elemento de la cola de la lógica y con cada transición anotada en el diario.

Servidor: lectura

Herramienta	Qué hace
`server_status`	Informa del estado de salud del servidor OPC UA integrado: si está en marcha, el tiempo en marcha, la URL del punto de conexión, las sesiones de cliente conectadas y el tamaño del espacio de direcciones configurado.

Servidor: operación

Herramienta	Qué hace
`server_start`	Arranca el servidor OPC UA integrado, materializando la configuración actual. No hace nada cuando ya está en marcha.
`server_stop`	Detiene el servidor con orden. La comunicación con los dispositivos, las lecturas de tag y el espacio de direcciones en vivo de Logic se detienen hasta que vuelva a arrancar.
`server_restart`	Detener y luego arrancar, volviendo a materializar la configuración; la recarga completa tras un lote de cambios.
`connector_refresh`	Concilia de forma incremental el servidor en marcha con los dispositivos configurados (añade, quita, recrea) sin un reinicio completo; la forma más ligera de aplicar cambios.
`device_discover`	Ejecuta la exploración de descubrimiento de dispositivos de un controlador y devuelve candidatos con sus tags, sin guardar nada. Solo participan los controladores cuyo protocolo admite una exploración de verdad; los candidatos que ya existen se marcan como tales.

Diario técnico: lectura

Herramienta Qué hace

logs_read Lee el flujo de registro en vivo de todo el programa (el mismo de la Consola de Eventos), filtrado por gravedad mínima (Debug, Information, Warning o Error; Information por defecto), por área (App, Server, Connector, Logic, Process, Dashboard, Agent o Licensing), por componente y por una subcadena de contexto; devuelve las coincidencias más nuevas (100 por defecto, 500 como mucho). Las acciones de un agente se anotan bajo el área Agent.

event_history_read Lee la cronología permanente de eventos operativos, que sobrevive a los reinicios: transiciones de alarma, transiciones de incidencia y transiciones de enclavamiento. Se filtra por clase (Alarm, Occurrence o Interlock), por un periodo UTC inclusivo y por un nivel (prioridad de la alarma, gravedad de la incidencia o transición del enclavamiento); las más nuevas primero, 100 por defecto y 500 como mucho. Estrictamente de solo lectura: nada puede vaciar ni eliminar entradas del diario.

Herramienta	Qué hace
`logs_read`	Lee el flujo de registro en vivo de todo el programa (el mismo de la Consola de Eventos), filtrado por gravedad mínima (Debug, Information, Warning o Error; Information por defecto), por área (App, Server, Connector, Logic, Process, Dashboard, Agent o Licensing), por componente y por una subcadena de contexto; devuelve las coincidencias más nuevas (100 por defecto, 500 como mucho). Las acciones de un agente se anotan bajo el área Agent.
`event_history_read`	Lee la cronología permanente de eventos operativos, que sobrevive a los reinicios: transiciones de alarma, transiciones de incidencia y transiciones de enclavamiento. Se filtra por clase (Alarm, Occurrence o Interlock), por un periodo UTC inclusivo y por un nivel (prioridad de la alarma, gravedad de la incidencia o transición del enclavamiento); las más nuevas primero, 100 por defecto y 500 como mucho. Estrictamente de solo lectura: nada puede vaciar ni eliminar entradas del diario.

Process: lectura

Herramienta	Qué hace
`process_models`	Lista los modelos de Process por completo: canales, grupos compartidos, unidades con su cableado resuelto y su estado en marcha, procedimientos, paneles, recetas, evaluaciones, incidencias, más la biblioteca global de plantillas de informe. El mapa que lee un agente antes de arrancar nada.
`process_runs`	Lista los ensayos, del más reciente al más antiguo: id, nombre, estado, veredicto, qué corrió, quién lo arrancó (Station, User, Automation o Agent), tiempos y avance de los ciclos. Se puede restringir a los ensayos activos y acotar (50 por defecto).
`process_run`	Lee el registro congelado completo de un ensayo por su id: instantánea, metadatos, criterios juzgados con sus recuentos de muestras, episodios y eventos de incidencia, escrituras de receta tal como se ejecutaron, comentarios, y los artefactos congelados del informe y de la etiqueta con sus intentos de impresión. Si se le pide, calcula el número de filas del datalog y su rango de tiempo.
`unit_status`	Informa del estado en vivo de una unidad: si está en marcha (con el ensayo activo) y el valor de ingeniería actual que hay detrás de cada canal, leído sin grabar.

Process: configuración

Herramienta	Qué hace
`process_view_configure`	Configura exactamente un panel de un modelo: el icono que se dibuja a su lado y si aparece en la página View. Nada más del agregado de Process se puede escribir por MCP; el resto se edita en la página Process.

Process: operación

Los ensayos que un agente arranca, termina o comenta anotan Agente como el actor, nunca el operador que casualmente tenga la sesión iniciada en el banco de pruebas.

Herramienta	Qué hace
`process_snapshot`	Captura una fila de datalog en una unidad fuera de un procedimiento. Cada llamada crea un ensayo Instantáneo nuevo y ya completado en Históricos, sin evaluación (veredicto None).
`process_evaluate`	Captura una fila de datalog y la juzga con una evaluación; crea un ensayo Instantáneo completado y devuelve su veredicto.
`process_recipe_apply`	Aplica una vez una receta Instantánea a una unidad a través del punto único de escritura de Process y de los bloqueos de origen. Manda sobre el equipo; no crea ningún ensayo (las escrituras se anotan en el diario). Las recetas temporizadas se rechazan.
`process_start`	Arranca la ejecución de un procedimiento en una unidad, con un objeto JSON para los campos de metadatos del procedimiento. Unos metadatos obligatorios ausentes o no válidos, una unidad que ya está en marcha, o un conflicto de bloqueo de canal compartido rechazan el arranque. Devuelve el id del ensayo nuevo.
`process_stop`	Detiene un ensayo en marcha: bloque de finalización, instantánea de histórico congelada, veredicto calculado.
`process_hold`	Pausa el perfil temporizado de un ensayo en la última consigna; el datalog sigue grabando.
`process_resume`	Reanuda el perfil temporizado de un ensayo en pausa.
`process_abort`	Aborta un ensayo desde En marcha o En pausa: la finalización corre, la instantánea se escribe, el estado pasa a Abortado y el veredicto a NOK.
`process_comment`	Añade un comentario con marca de tiempo al archivo de un ensayo: una nota en la cronología mientras está activo, y una nota posterior al ensayo después.
`process_report`	Genera (o vuelve a generar) el informe PDF de un ensayo terminado y devuelve la ruta de su archivo. Una plantilla con nombre de la biblioteca global sustituye a la configurada en el procedimiento; sin ninguna de las dos, se aplica el diseño por defecto con todas las secciones. Se rechaza mientras el ensayo está activo.
`process_run_delete`	Elimina de forma permanente un ensayo grabado: su puntero en el índice del histórico y el archivo de base de datos de ese ensayo. Se rechaza mientras está activo; la configuración no se toca.

Paneles de control: configuración

Herramienta	Qué hace
`dashboard_list`	Lista los paneles de control (o, si se nombra un modelo, los sinópticos de ese modelo): tamaño de la rejilla, carpeta, icono, bandera de arranque, visibilidad por rol y todos los componentes con su posición, su capa y su JSON de propiedades, más todas las redes de trazos guardadas. Devuelve además el catálogo de clases de componente con el tamaño por defecto y la bolsa de propiedades por defecto de cada clase.
`dashboard_upsert`	Crea o actualiza un panel de control por su nombre: tamaño de la rejilla (un encogimiento que dejaría huérfano a un componente se rechaza), carpeta e icono de la lista de Visualización, bandera de arranque, visibilidad de la barra de estado a pantalla completa, y visibilidad por rol. Nombrar un modelo direcciona en su lugar los sinópticos de ese modelo. Las páginas de panel de control abiertas reflejan el cambio en vivo.
`dashboard_delete`	Elimina un panel de control y sus componentes por su nombre; nombrar un modelo elimina en su lugar el sinóptico de ese modelo.
`component_upsert`	Añade un componente por su clase (colocado en la primera celda libre con el tamaño por defecto de la clase, salvo que se le diga otra cosa) o actualiza uno por su id. La colocación tiene que caer dentro de la rejilla; se admite el solapamiento, y la capa z decide el orden de dibujo; el JSON de propiedades es la bolsa tipada de la clase. Nombrar un modelo direcciona en su lugar los sinópticos de ese modelo, así que un sinóptico creado allí se puede componer aquí.
`component_delete`	Quita un componente por su id; nombrar un modelo direcciona en su lugar los sinópticos de ese modelo.
`connection_upsert`	Une dos bornes de Símbolo con una red de trazos tipada, resolviendo el tipo, el papel y la orientación desde el catálogo de símbolos exactamente igual que el editor del lienzo. Los extremos que resuelven a tipos distintos fallan salvo que se permita de forma explícita un trazo indefinido; un anclaje que ya lleva un trazo se rechaza. Nombrar un modelo direcciona en su lugar los sinópticos de ese modelo.
`connection_delete`	Quita una red de trazos por su id y por la revisión esperada, para que una eliminación caducada se rechace en vez de pisar una edición más nueva; nombrar un modelo direcciona en su lugar los sinópticos de ese modelo.

Interfaz: automatización

Estas herramientas gobiernan la ventana real de la aplicación; existen para que un agente pueda verificar la interfaz que ve el operador, y no una simulación de ella. Las interacciones se despachan al shell en vivo, así que la conducta prevista es seguir cada gesto con ui_screenshot y observar el efecto, y las coincidencias ambiguas vuelven como listas de candidatos en lugar de como un clic adivinado.

Herramienta	Qué hace
`ui_state`	Informa del estado del shell: página activa, páginas disponibles, tema, tamaño y visibilidad de la ventana, y la dirección loopback en la que esta instancia sirve su interfaz. La llamada de orientación antes que cualquier otra cosa.
`ui_navigate`	Activa una página del shell por su nombre estable, que está en inglés en toda estación: `View`, `Process`, `Logic`, `Connector`, `Users`, `Validation`, `Events`, `Agent`, `Settings`, `Account`. También se acepta el rótulo que la barra de navegación muestra en el idioma de la estación.
`ui_screenshot`	Captura la ventana tal como se ve en pantalla en un archivo PNG y devuelve su ruta absoluta; primero restaura la ventana cuando está escondida en el área de notificación. Puede capturar una región de pantalla con nombre (un área `data-doc-region` única y visible) en lugar de la ventana entera, y una región ausente, escondida o ambigua falla listando las regiones visibles, en vez de recaer en silencio en una captura completa.
`ui_scroll`	Desplaza la región de desplazamiento principal de la página activa al principio, al final o por páginas de la vista, devolviendo los desplazamientos para poder barrer una página larga.
`ui_set_theme`	Aplica el tema (Sistema, Claro u Oscuro). Se guarda exactamente igual que el menú de tema de la barra de título, así que un agente bien educado restaura el valor original al terminar.
`ui_resize`	Cambia el tamaño de la ventana restaurada en unidades independientes del dispositivo, recortado al mínimo de la ventana; útil para auditar disposiciones compactas.
`ui_click`	Pulsa el botón, el hipervínculo, la casilla o el conmutador visible cuyo texto coincide; las casillas y los conmutadores se encuentran por la etiqueta de su campo y el resultado informa del estado en el que quedaron. La ambigüedad devuelve los candidatos en vez de elegir uno.
`ui_set_text`	Escribe un valor en un cuadro de texto identificado por la etiqueta de su campo, confirmando el vínculo igual que haría escribir a mano.
`ui_select`	Selecciona un elemento por su texto visible: una ruta separada por barras recorre un árbol, desplegándolo por el camino; un solo segmento coincide también con elementos de lista, de pestaña y de cuadro combinado y con filas de rejilla de la página actual.

Copias de seguridad: gestión

Herramienta	Qué hace
`backup_create`	Crea una instantánea en caliente de la base de datos de configuración en la carpeta de copias de seguridad, con una nota opcional. Los ensayos grabados viven fuera de la configuración y ni la copia ni la restauración los tocan nunca.
`backup_list`	Lista las copias de seguridad de la configuración (nombre del archivo, fecha de creación, tamaño, nota) más cualquier restauración ya programada.

A propósito no hay ninguna herramienta que elimine copias de seguridad: la retención es solo del operador, en la página Copias de seguridad.

Copias de seguridad: restauración

Herramienta Qué hace

backup_restore Programa una copia de seguridad para que sustituya la configuración actual en el siguiente arranque de la aplicación. En la aplicación en marcha no cambia nada y la herramienta nunca la reinicia; de la configuración que se va a sustituir se hace antes una instantánea automática, y el operador puede cancelar la restauración pendiente desde Ajustes hasta el reinicio. Se rechaza mientras hay una grabación activa.

Herramienta	Qué hace
`backup_restore`	Programa una copia de seguridad para que sustituya la configuración actual en el siguiente arranque de la aplicación. En la aplicación en marcha no cambia nada y la herramienta nunca la reinicia; de la configuración que se va a sustituir se hace antes una instantánea automática, y el operador puede cancelar la restauración pendiente desde Ajustes hasta el reinicio. Se rechaza mientras hay una grabación activa.

Ajustes: gestión

Herramienta	Qué hace
`settings_read`	Lee las preferencias de presentación y de ciclo de vida de la estación: formatos de fecha, hora y número, decimales, tema, y las banderas de cerrar al área de notificación y de informes de fallo.
`localization_set`	Actualiza las preferencias de presentación (parcial: los parámetros omitidos se quedan). Solo presentación: el almacenamiento, la entrada y salida de los controladores y las grabaciones usan siempre el formato invariable.
`asset_list`	Lista los recursos de usuario (imágenes, iconos, colores) con sus ids, sus valores y sus rutas.
`asset_import`	Importa un PNG o un JPG desde una ruta de archivo local a la biblioteca de recursos que gobierna la aplicación y devuelve el id del recurso nuevo. Los bytes se copian, así que el archivo de origen se puede mover después.
`symbol_validate`	Valida contenido de símbolo en línea (SVG en bruto o un paquete v2) sin guardar nada: un ensayo en seco de la importación exacta, que devuelve errores, advertencias del saneador y un resumen de lo que se reconoció. La descripción de la herramienta lleva el contrato completo de símbolo portátil.
`symbol_import`	Importa contenido de símbolo en línea como un recurso de símbolo de usuario nuevo y devuelve su id y su referencia `user:<guid>`. Siempre crea un recurso nuevo; un nombre que choca recibe un sufijo automático.