paperclip-plugin-autopilot-ops 0.0.0-stage → 0.1.5

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# Autopilot Care · plugin `autopilot-ops` para Paperclip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Operación autónoma gobernada para instituciones de salud. Este plugin es la capa
+determinística que corre **dentro** de Paperclip (mismo proceso de plugins, misma
+base, misma UI): workflows por puesto, validaciones de negocio, registro de cada
+acción con su evidencia, políticas de autonomía con circuito de corte y el tablero
+del director. Los agentes de Paperclip no tocan nada directo: deciden y llaman
+herramientas de este plugin; el tool gateway de Paperclip autoriza; el plugin
+ejecuta y registra.
+
+Arquitectura completa: documento *Arquitectura Autopilot Care sobre Paperclip*.
+
+## Qué hay adentro
+
+| Capa | Dónde | Qué hace |
+| --- | --- | --- |
+| Workflows | `src/workflows.ts` | Estados, tabla de transiciones, quién puede ejecutar cada una, validaciones puras. Sin IA. |
+| Registro de negocio | `migrations/001_autopilot_ops.sql`, `src/ops.ts` | Tablas `caso`, `transicion`, `accion`, `politica`, `politica_historial` en el namespace del plugin. Todo lleva `company_id`. |
+| Herramientas para agentes | `src/worker.ts` (`ctx.tools`) | `ops_listar_casos`, `ops_leer_caso`, `ops_abrir_caso`, `ops_transicionar`, `ops_registrar_accion`, `ops_consultar_indicador`, `ops_publicar_tablero`, `ops_listar_tableros`. Pasan por el tool gateway. |
+| Tableros del hospital | `migrations/002_tableros.sql`, `src/tableros.ts` | Tabla `tablero`: lo que publica el Agente de tableros sobre los datos de Alephoo (clave estable, título, período, fuentes, widgets). El plugin valida la forma de los widgets; el portal los dibuja. |
+| Gobierno | `politica` + UI | Modo por workflow e institución: `corte` · `observa` · `propone` · `ejecuta` · `autonomo` (aprobación por excepción: salta a aprobado salvo que una regla de excepción se dispare: variación > 20 %, sin valor actual, reintento tras diferencias, baja de valor). Default `propone`. |
+| Tablero del director | `src/ui/index.tsx` | Pantalla `/<empresa>/autopilot`: horas absorbidas, pendientes de aprobación con Aprobar / Rechazar, estado por puesto, políticas y corte. |
+| API para el portal | `apiRoutes` (auth `board`) | `GET /tablero`, `GET /serie`, `GET /casos`, `GET /casos/:id`, `POST /casos/:id/aprobar`, `POST /casos/:id/rechazar`, `POST /casos/:id/cargado`, `GET /politicas`, `GET /politicas/historial`, `POST /politicas`, `GET /tableros`, `GET /tableros/:clave`, `GET /version`. Montadas en `/api/plugins/alephoo.autopilot-ops/api/*`. |
+
+### Workflows incluidos
+
+**`actualizacion_arancel`** (puesto Convenios y facturación, 25 min absorbidos por caso)
+
+```
+detectado ─proponer(agente)→ pendiente_aprobacion ─aprobar(humano)→ aprobado ─aplicar(agente en ejecuta, o persona: carga manual)→ aplicado ─verificar→ verificado
+                                      └rechazar(humano)→ rechazado                                                                  └→ con_diferencias ─proponer→ …
+                                                                                                                                                       └corregir(persona)→ aplicado
+```
+
+Validaciones de `proponer`: valor nuevo > 0, vigencia `AAAA-MM-DD`, fuente
+obligatoria, variación > 50 % requiere justificación. `aplicar` exige el id de la
+escritura registrada con `ops_registrar_accion`. `verificar` compara el valor
+releído con el aprobado y decide el destino.
+
+**`tarea_operativa`** (genérico, 15 min): `abierta → en_curso → pendiente_aprobacion → cerrada | rechazada`.
+
+### Reglas que el plugin impone siempre
+
+- `aprobar`, `rechazar`, `cancelar` y cambiar la política son **solo humanas**.
+- `companyId` viene del host (contexto de ejecución del agente, bridge de la UI o
+  ruta API). Un agente no puede ver ni tocar casos de otra institución.
+- Un agente solo registra **escrituras** sobre el sistema del hospital si el
+  workflow está en modo `ejecuta`.
+- En `corte` el agente no abre ni mueve casos.
+- Si una validación falla, el caso no cambia y el agente recibe el motivo con un
+  código estable (`validacion: fuente_presente: …`).
+- Toda transición y acción queda en el registro; además se escribe en el
+  activity log de Paperclip.
+- `idempotencyKey` en `ops_abrir_caso` y `ops_transicionar` hace los reintentos
+  seguros; `referencia` evita abrir dos casos sobre el mismo objeto.
+- Quien carga no se controla a sí mismo: una carga manual la comprueba después
+  el agente releyendo el sistema (`verificar`).
+
+### Carga manual del equipo del hospital (0.1.5)
+
+En `propone` el agente no escribe en Alephoo: lo aprobado lo carga una persona
+del hospital. El portal lo muestra en **Para cargar** y la persona lo marca con
+`POST /casos/:id/cargado` (`valorCargado?`, `comentario?`, `decididoPor`,
+`idempotencyKey?`), o la acción `marcar-cargado` desde la UI de Paperclip:
+
+- El plugin registra una **escritura manual** (`conector: "manual"`) con su
+  evidencia (`cargado_por`, `valor_cargado`, `valor_aprobado`, `vigencia_desde`,
+  `nota`) y mueve el caso con la transición de carga de su estado: `aplicar`
+  desde `aprobado`, o `corregir` desde `con_diferencias` (una carga que no
+  coincidió se corrige y se vuelve a comprobar sin otra aprobación, porque el
+  valor aprobado no cambia; `corregir` es solo humana y descarta la lectura anterior).
+- Antes de escribir evalúa la transición; si el caso no está para cargar,
+  responde `estado_invalido` con el motivo y no toca nada.
+- Después el agente comprueba: lee el valor en Alephoo, registra la
+  verificación y llama `verificar` con `datos.valor_leido`. El portal se lo pide
+  con una tarea en Paperclip (`Comprobar carga: …`, asignada al agente del caso).
+- `GET /version` devuelve `{version, capacidades: ["carga-manual"]}`: el portal
+  lo usa para saber si el plugin instalado ya registra cargas.
+
+### Tableros publicados por agentes (0.1.4)
+
+El Agente de tableros no mueve casos: lee Alephoo por API, calcula lo que pidió
+la dirección y publica el resultado con `ops_publicar_tablero`:
+
+```json
+{
+  "clave": "turnos-ausentismo",
+  "titulo": "Turnos y ausentismo por servicio",
+  "pedido": "Quiero ver cuántos turnos damos por servicio y cuántos pacientes faltan",
+  "periodo": "septiembre 2026",
+  "fuentes": ["Alephoo · api-consultas · turnos 01/09–30/09"],
+  "widgets": [
+    { "tipo": "indicador", "etiqueta": "Turnos dados", "valor": 1842, "contexto": "22 días hábiles", "tono": "senal" },
+    { "tipo": "barras", "titulo": "Turnos por servicio", "series": [{ "etiqueta": "Clínica", "valor": 620 }] },
+    { "tipo": "linea", "titulo": "Turnos por día", "puntos": [{ "x": "2026-09-01", "y": 61 }] },
+    { "tipo": "tabla", "titulo": "Más ausentes", "columnas": ["Profesional", "Ausentes"], "filas": [["Dra. Medina", 14]] },
+    { "tipo": "texto", "titulo": "Lectura", "texto": "El ausentismo baja 1,5 puntos." }
+  ],
+  "issueId": "<uuid de la tarea que lo pidió>"
+}
+```
+
+- `clave` es estable: volver a publicar con la misma clave actualiza el tablero
+  en el lugar y suma una versión (`ops_listar_tableros` muestra las existentes).
+- Tipos de widget: `indicador`, `barras`, `linea`, `tabla`, `texto`; `ancho` 1–3
+  opcional. La validación devuelve todos los problemas juntos
+  (`tablero_invalido: widgets[2].filas[0] tiene 1 celdas y la tabla 2 columnas`).
+- El portal del hospital los muestra en la sección **Tableros**; los pedidos de
+  la dirección llegan como tareas de Paperclip con título `Tablero: …`.
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm verify        # typecheck + tests + build
+pnpm dev           # esbuild en modo watch (dist/manifest.js, dist/worker.js, dist/ui/)
+```
+
+Tests (`tests/`): motor de workflows, cableado de herramientas / acciones / rutas
+con el harness del SDK, y `sql.spec.ts`, que pasa la migración y todo el SQL de
+ejecución por una copia del validador de SQL del propio host Paperclip.
+
+### Agregar un workflow
+
+1. Definirlo en `src/workflows.ts` (estados, `inicial`, finales, `minutosAbsorbidos`, transiciones con `actor`, `nivelRequerido` y `validar`).
+2. Agregarlo a `WORKFLOWS`. No hace falta tocar la base: los casos son genéricos.
+3. Los tests de `tests/workflows.spec.ts` verifican invariantes para todos los workflows.
+
+## Instalación en una instancia Paperclip
+
+Paperclip instala plugins de dos formas (`POST /api/plugins/install`, solo
+administradores de instancia):
+
+1. **Desde npm** (la pantalla *Settings → Plugins → Install Plugin* solo acepta
+   un nombre de paquete npm): la instancia corre `npm install <paquete>` en su
+   directorio de plugins. Requiere publicar este paquete como
+   `paperclip-plugin-autopilot-ops`:
+
+   ```bash
+   pnpm install && pnpm verify   # deja dist/ construido; la instalación corre con --ignore-scripts
+   npm login
+   npm publish
+   ```
+
+   Después, en la pantalla, escribir `paperclip-plugin-autopilot-ops` e Install.
+2. **Desde una ruta local del servidor**: clonar este repositorio en la máquina
+   donde corre Paperclip, `pnpm install && pnpm build`, y luego
+   `paperclipai plugin install /ruta/al/plugin` (o la misma pantalla con la
+   opción de ruta local). En desarrollo, `pnpm dev` deja el worker recargando.
+
+Después de instalar, el agente que va a usar las herramientas necesita un
+**perfil de herramientas** que permita las de este plugin (Agent settings →
+Tools); el gateway niega por defecto todo lo que no está permitido.
+
+## Primer caso de uso (MVP)
+
+Agente `Turnos`/`Convenios` detecta un cambio de arancel en el sistema de
+gestión → `ops_abrir_caso` (`actualizacion_arancel`, referencia = convenio +
+práctica) → `ops_registrar_accion` (lectura, evidencia) → `ops_transicionar`
+`proponer` con `valor_nuevo`, `vigencia_desde`, `fuente` → el responsable del
+hospital ve el caso en *Pendientes de aprobación* y aprueba → en modo `ejecuta`,
+el agente aplica, registra la escritura y verifica → el tablero suma 25 minutos
+absorbidos.

package/dist/manifest.js

@@ -0,0 +1,311 @@
+// src/manifest.ts
+var PLUGIN_ID = "alephoo.autopilot-ops";
+var PLUGIN_VERSION = "0.1.5";
+var DB_NAMESPACE_SLUG = "autopilot_ops";
+var PAGE_ROUTE = "autopilot";
+var TOOL_NAMES = {
+  listarCasos: "ops_listar_casos",
+  leerCaso: "ops_leer_caso",
+  abrirCaso: "ops_abrir_caso",
+  transicionar: "ops_transicionar",
+  registrarAccion: "ops_registrar_accion",
+  consultarIndicador: "ops_consultar_indicador",
+  publicarTablero: "ops_publicar_tablero",
+  listarTableros: "ops_listar_tableros"
+};
+var DATA_KEYS = {
+  tablero: "tablero",
+  serie: "serie",
+  historialPoliticas: "historial-politicas",
+  casos: "casos",
+  caso: "caso",
+  politicas: "politicas",
+  workflows: "workflows"
+};
+var ACTION_KEYS = {
+  aprobar: "aprobar",
+  rechazar: "rechazar",
+  marcarCargado: "marcar-cargado",
+  cambiarPolitica: "cambiar-politica",
+  abrirCaso: "abrir-caso"
+};
+var manifest = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "Autopilot Care",
+  description: "Operaci\xF3n aut\xF3noma gobernada para instituciones de salud: workflows determin\xEDsticos por puesto, validaciones, registro de negocio con evidencia, pol\xEDticas (observa / propone / ejecuta / aut\xF3nomo / corte), carga manual del equipo del hospital con comprobaci\xF3n del agente, tableros de gesti\xF3n publicados por agentes y panel del director.",
+  author: "Alephoo",
+  categories: ["automation", "ui"],
+  capabilities: [
+    "database.namespace.migrate",
+    "database.namespace.read",
+    "database.namespace.write",
+    "agent.tools.register",
+    "api.routes.register",
+    "activity.log.write",
+    "companies.read",
+    "ui.sidebar.register",
+    "ui.page.register"
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui"
+  },
+  database: {
+    namespaceSlug: DB_NAMESPACE_SLUG,
+    migrationsDir: "migrations",
+    coreReadTables: ["companies", "agents", "issues"]
+  },
+  tools: [
+    {
+      name: TOOL_NAMES.listarCasos,
+      displayName: "Listar casos",
+      description: "Lista casos del registro de negocio de la instituci\xF3n. Filtros opcionales: workflow, estado, limit (m\xE1x. 100). Solo lectura.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          workflow: { type: "string" },
+          estado: { type: "string" },
+          limit: { type: "number" }
+        }
+      }
+    },
+    {
+      name: TOOL_NAMES.leerCaso,
+      displayName: "Leer caso",
+      description: "Devuelve un caso con su historial de transiciones y acciones registradas. Solo lectura.",
+      parametersSchema: {
+        type: "object",
+        properties: { casoId: { type: "string" } },
+        required: ["casoId"]
+      }
+    },
+    {
+      name: TOOL_NAMES.abrirCaso,
+      displayName: "Abrir caso",
+      description: "Abre un caso nuevo en un workflow, en su estado inicial. `referencia` identifica el objeto real (convenio, cuenta, profesional) y evita duplicados: si ya existe un caso abierto con la misma referencia, se devuelve ese. Pasar `idempotencyKey` para reintentos seguros.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          workflow: { type: "string" },
+          referencia: { type: "string" },
+          titulo: { type: "string" },
+          datos: { type: "object" },
+          idempotencyKey: { type: "string" },
+          issueId: { type: "string", description: "Tarea de Paperclip que origina el caso (opcional; UUID)." }
+        },
+        required: ["workflow", "titulo"]
+      }
+    },
+    {
+      name: TOOL_NAMES.transicionar,
+      displayName: "Transicionar caso",
+      description: "Aplica una transici\xF3n del workflow al caso (p. ej. `proponer`, `aplicar`, `verificar`). El plugin valida contra la tabla de transiciones, la pol\xEDtica vigente (observa / propone / ejecuta / corte) y las reglas de negocio; si algo falla, el caso no cambia y se devuelve el motivo. Las transiciones humanas (aprobar, rechazar, corregir) no est\xE1n disponibles para agentes. Cuando una persona del hospital carga a mano lo aprobado, el caso queda en `aplicado`: el agente lo comprueba releyendo el sistema y llamando `verificar` con `datos.valor_leido`.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          casoId: { type: "string" },
+          via: { type: "string" },
+          datos: { type: "object" },
+          motivo: { type: "string" },
+          idempotencyKey: { type: "string" }
+        },
+        required: ["casoId", "via"]
+      }
+    },
+    {
+      name: TOOL_NAMES.registrarAccion,
+      displayName: "Registrar acci\xF3n",
+      description: "Registra una acci\xF3n ejecutada sobre un sistema externo (lectura, escritura o verificaci\xF3n) con su evidencia. Toda acci\xF3n sobre el sistema del hospital debe quedar registrada ac\xE1.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          casoId: { type: "string" },
+          tipo: { type: "string", enum: ["lectura", "escritura", "verificacion"] },
+          conector: { type: "string", enum: ["api", "archivo", "pantalla", "manual"] },
+          objetivo: { type: "string" },
+          resultado: { type: "string", enum: ["ok", "error", "pendiente"] },
+          evidencia: { type: "object" },
+          detalle: { type: "string" }
+        },
+        required: ["casoId", "tipo", "conector", "objetivo", "resultado"]
+      }
+    },
+    {
+      name: TOOL_NAMES.consultarIndicador,
+      displayName: "Consultar indicador",
+      description: "Devuelve indicadores calculados del registro de negocio (los mismos que ve el director): `resumen`, `por_estado`, `pendientes`, `horas`. Solo lectura.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          indicador: { type: "string", enum: ["resumen", "por_estado", "pendientes", "horas"] },
+          workflow: { type: "string" },
+          dias: { type: "number" }
+        },
+        required: ["indicador"]
+      }
+    },
+    {
+      name: TOOL_NAMES.publicarTablero,
+      displayName: "Publicar tablero",
+      description: "Publica o actualiza un tablero de gesti\xF3n para la direcci\xF3n del hospital, armado sobre datos reales de Alephoo (turnos, facturaci\xF3n, internaci\xF3n, producci\xF3n). `clave` identifica el tablero de forma estable (min\xFAsculas y guiones; volver a publicar con la misma clave lo actualiza en el lugar). `widgets` es la lista de piezas que se muestran, en orden: {tipo:'indicador', etiqueta, valor, unidad?, contexto?, tono?: neutro|ambar|senal|corte} \xB7 {tipo:'barras', titulo, unidad?, series:[{etiqueta, valor}]} \xB7 {tipo:'linea', titulo, unidad?, puntos:[{x, y}]} \xB7 {tipo:'tabla', titulo, columnas:[\u2026], filas:[[\u2026]]} \xB7 {tipo:'texto', titulo?, texto}. Cada widget admite `ancho` 1, 2 o 3 (columnas de 3). `fuentes` lista qu\xE9 se consult\xF3 (p. ej. 'Alephoo \xB7 api-consultas \xB7 turnos 01/09\u201330/09'). Si el pedido vino de una tarea, pasar `issueId`.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          clave: { type: "string" },
+          titulo: { type: "string" },
+          descripcion: { type: "string" },
+          pedido: { type: "string", description: "Qu\xE9 pidi\xF3 la direcci\xF3n, en sus palabras." },
+          periodo: { type: "string", description: "Per\xEDodo que cubren los datos, p. ej. 'septiembre 2026'." },
+          fuentes: { type: "array", items: { type: "string" } },
+          widgets: { type: "array", items: { type: "object" } },
+          issueId: { type: "string", description: "Tarea de Paperclip que origin\xF3 el tablero (opcional; UUID)." }
+        },
+        required: ["clave", "titulo", "widgets"]
+      }
+    },
+    {
+      name: TOOL_NAMES.listarTableros,
+      displayName: "Listar tableros",
+      description: "Lista los tableros publicados para esta instituci\xF3n (clave, t\xEDtulo, per\xEDodo, fuentes, cu\xE1ndo se actualiz\xF3 y cu\xE1ntos widgets tiene). Usar antes de publicar para reutilizar la clave de un tablero existente en vez de crear uno nuevo. Solo lectura.",
+      parametersSchema: { type: "object", properties: {} }
+    }
+  ],
+  apiRoutes: [
+    {
+      routeKey: "tablero",
+      method: "GET",
+      path: "/tablero",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "casos",
+      method: "GET",
+      path: "/casos",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "caso",
+      method: "GET",
+      path: "/casos/:casoId",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "aprobar",
+      method: "POST",
+      path: "/casos/:casoId/aprobar",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "rechazar",
+      method: "POST",
+      path: "/casos/:casoId/rechazar",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "marcar-cargado",
+      method: "POST",
+      path: "/casos/:casoId/cargado",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "version",
+      method: "GET",
+      path: "/version",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "serie",
+      method: "GET",
+      path: "/serie",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "historial-politicas",
+      method: "GET",
+      path: "/politicas/historial",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "politicas",
+      method: "GET",
+      path: "/politicas",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "cambiar-politica",
+      method: "POST",
+      path: "/politicas",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "tableros",
+      method: "GET",
+      path: "/tableros",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "tablero-publicado",
+      method: "GET",
+      path: "/tableros/:clave",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    }
+  ],
+  ui: {
+    slots: [
+      {
+        type: "sidebar",
+        id: "autopilot-sidebar",
+        displayName: "Autopilot Care",
+        exportName: "SidebarLink",
+        order: 30
+      },
+      {
+        type: "page",
+        id: "autopilot-page",
+        displayName: "Autopilot Care",
+        exportName: "TableroPage",
+        routePath: PAGE_ROUTE
+      }
+    ]
+  }
+};
+var manifest_default = manifest;
+export {
+  ACTION_KEYS,
+  DATA_KEYS,
+  DB_NAMESPACE_SLUG,
+  PAGE_ROUTE,
+  PLUGIN_ID,
+  PLUGIN_VERSION,
+  TOOL_NAMES,
+  manifest_default as default
+};
+//# sourceMappingURL=manifest.js.map