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

package/README.md

@@ -1,3 +1,107 @@
-# 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`. Pasan por el tool gateway. |
+| Gobierno | `politica` + UI | Modo por workflow e institución: `corte` · `observa` · `propone` · `ejecuta`. 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 /casos`, `GET /casos/:id`, `POST /casos/:id/aprobar`, `POST /casos/:id/rechazar`, `GET /politicas`, `POST /politicas`. 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, modo ejecuta)→ aplicado ─verificar→ verificado
+                                      └rechazar(humano)→ rechazado                                             └→ con_diferencias ─proponer→ …
+```
+
+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.
+
+## 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,232 @@
+// src/manifest.ts
+var PLUGIN_ID = "alephoo.autopilot-ops";
+var PLUGIN_VERSION = "0.1.0";
+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"
+};
+var DATA_KEYS = {
+  tablero: "tablero",
+  casos: "casos",
+  caso: "caso",
+  politicas: "politicas",
+  workflows: "workflows"
+};
+var ACTION_KEYS = {
+  aprobar: "aprobar",
+  rechazar: "rechazar",
+  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 / corte) y tablero 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" }
+        },
+        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) no est\xE1n disponibles para agentes.",
+      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"]
+      }
+    }
+  ],
+  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: "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" }
+    }
+  ],
+  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