@patroltech/agent-capabilities 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ingenieros Web SL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# PatrolTech agent capabilities
 
-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.
+Channel-agnostic building blocks to let an AI agent **read and act on a PatrolTech account**: rounds, routes, checkpoints, guards, incidents, users, locations, access control and scans. The same catalog powers the PatrolTech chat assistant (WhatsApp and Telegram) and the [PatrolTech MCP connector](https://mcp.patroltech.online/mcp).
+
+[![CI](https://github.com/PatrolTech/agent-capabilities/actions/workflows/ci.yml/badge.svg)](https://github.com/PatrolTech/agent-capabilities/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@patroltech/agent-capabilities)](https://www.npmjs.com/package/@patroltech/agent-capabilities)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+- **Reads** return a `ToolResult` the model can read (`{ ok, data, avisos }` or `{ ok: false, error }`).
+- **Actions** never write on their own: each one _prepares_ a proposal, your app shows its summary to the user, and only after the user confirms does it _execute_.
+- Built on the official SDK [`@patroltech/sdk-api`](https://github.com/PatrolTech/sdk-api), generated from the public OpenAPI contract. Every operation the catalog calls is checked against that contract in CI.
+- No channel, database, logger or LLM framework inside: everything external comes in through small ports.
+
+> **This package grants no access by itself.** Every call carries the user's token and the PatrolTech API authorizes it (organization and location roles, OAuth scopes and, for MCP agents, a closed list of allowed writes). The checks in this package only produce better messages.
+
+## Install
+
+```bash
+npm install @patroltech/agent-capabilities zod
+```
+
+Node.js 22 or later. `zod` 4 is a peer dependency (the capabilities describe their parameters with it). The package is ESM.
+
+## Quick start
+
+```ts
+import {
+  SdkPatrolTechGateway,
+  buildCatalog,
+  noopLogger,
+  type CapabilityContext,
+} from '@patroltech/agent-capabilities';
+
+const gateway = new SdkPatrolTechGateway({
+  baseUrl: 'https://api.patroltech.online',
+  logger: noopLogger, // or your own { info, warn, error }
+  timeoutMs: 10_000,
+});
+
+// Build once. In the `mcp` channel only operational capabilities are offered, with neutral texts.
+const { reads, actions } = buildCatalog({ gateway }, { channel: 'mcp' });
+
+// Per call: the user's session. The token is a PatrolTech API session token
+// (see the OAuth flow in @patroltech/sdk-api); `organizations` come from that session.
+const org = { orgId: 'org-123', name: 'Acme Security', roleType: 'EDITOR', scope: 'organization' };
+const ctx: CapabilityContext = {
+  org,
+  organizations: [org],
+  token: apiSessionToken,
+  tz: 'Europe/Madrid',
+  country: 'ES',
+  language: 'en',
+};
+
+const status = reads.find(({ meta }) => meta.id === 'rounds.get_status');
+const result = await status?.read.call(ctx, {});
+// result: { ok: true, data: ... } or { ok: false, error: '...' } (never a raw API error)
+```
+
+Each entry comes with its metadata (`meta`): a stable `id` (`rounds.get_status`), `title` and `summary` in English and Spanish, `returns` (how to read the result, for reads), `readOnly`, `destructive`, `scope` and the SDK `operationIds` it calls. MCP servers should describe tools with `meta.title`, `meta.summary` and `meta.returns`. For English tool schemas, `englishInputSchema(meta.id, params)` translates the parameter names and descriptions, `argsFromEnglish` maps the arguments back and `englishFields` translates the output field names (and the fixed incident status and priority labels, to the values the English params use). Texts written for people (summaries, notices, reasons) follow the language of the user.
+
+### One gateway, many users
+
+`SdkPatrolTechGateway` keeps no global state: each call builds its own SDK configuration (base URL, token, `fetch`, timeout) with `createApiClient`, so one instance can serve any number of users concurrently. Options:
+
+| Option           | Default        | Notes                                                                                                                                 |
+| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`        | required       | API origin, without `/api`.                                                                                                           |
+| `fetchImpl`      | global `fetch` | For tests or instrumentation.                                                                                                         |
+| `timeoutMs`      | `10000`        | Per call, with `AbortSignal.timeout`.                                                                                                 |
+| `logger`         | no-op          | Receives failures with their detail; the model never does.                                                                            |
+| `defaultHeaders` | none           | `() => Record<string, string>`, evaluated per request (for example `X-Request-Id`). Any `Authorization` header it returns is dropped. |
+
+API rejections surface as `PatrolTechApiError` (status, path and body). `translateBackendError(err, language, options)` turns them into a message for the user in Spanish, English or French. `callSdk(config, token, path, call)` runs any other `@patroltech/sdk-api` function the same way (per-call config, timeout, errors as `PatrolTechApiError`).
+
+## Proposals and confirmation
+
+Write actions follow a propose → confirm → execute flow:
+
+1. `action.preparar(ctx, params)` resolves names to ids, checks limits and returns the parameters to store, or `{ error }` for the model.
+2. Your app stores the proposal in a `PendingActionStore` and shows `action.resumen(params, { idioma, organizacion })` to the user.
+3. When the user confirms, claim it with `claimForExecution` and run `action.ejecutar(ctx, params)` with the session of that moment.
+
+Batch helpers (`reservarEnLote`, `liberarEnLote`, `aceptarEnLote`, `huellaDePropuesta`, `MAX_POR_LOTE`) cap a batch at 10 proposals and drop duplicates. They protect the user from model mistakes; they are not a security barrier (the API is).
+
+### `PendingActionStore` and the `contextKey` rule
+
+`PendingActionStore` is a port: implement it on your own storage (a database table, Redis, memory for a single-process server). Proposals are indexed by a `contextKey`.
+
+**Bind the `contextKey` to the user _and_ to the conversation or client session**, for example `<userId>:<conversationId>` in a chat bot or `<userId>:<clientId>:<sessionId>` in an MCP server, and never share it between users. Whoever holds a `contextKey` can see, confirm or cancel the proposals stored under it. Also check, when executing, that the session user is still the one who proposed.
+
+## Ports
+
+| Port                 | What it does                                                               | Who implements it                                              |
+| -------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `PatrolTechGateway`  | Every call to the PatrolTech API.                                          | `SdkPatrolTechGateway` (included) or a test double.            |
+| `PendingActionStore` | Stores proposals until the user confirms them, by `contextKey`.            | You (database, Redis, memory).                                 |
+| `FileSink`           | Where generated files go (checkpoint QR codes, CSV exports). One per call. | You: a chat sends them, an MCP server returns them as content. |
+| `Logger`             | Traces and failures. `noopLogger` if you want none.                        | You.                                                           |
+
+`FileSink` goes in the call context (`ctx.files`), never in the shared dependencies: a sink shared between users would send one user's files to another. File capabilities are only offered with `buildCatalog({ gateway, offerFiles: true }, …)`.
+
+## Channels
+
+- **`mcp`**: operational reads and the writes the PatrolTech API allows to agents. Destructive or sensitive actions (deleting a time window or a location, archiving or moving a checkpoint, anti-fraud settings, changing or removing a user's access), actions that give access to someone else (inviting a user, creating a guard) and billing links are not offered. Texts never mention plans or upgrades (`upsell: false`).
+- **`bot`**: everything, for a first-party assistant where the user talks to PatrolTech directly.
+
+Every catalog entry declares its channels; the tests check that no `mcp` capability calls an operation that grants access and that its writes are exactly the ones the API allows to agents.
+
+## Prompt injection
+
+Names of routes, checkpoints, locations and guards, incident texts and user names are written by people in the account and reach the model as data inside `ToolResult`. Treat them as data, never as instructions (for example, wrap tool results with a note saying so), and keep the human confirmation of every write.
+
+## Testing
+
+`@patroltech/agent-capabilities/testing` exports `FakePatrolTechGateway` (in-memory, with fictitious data), `RecordingFileSink` and helpers to build read contexts.
+
+## Contract checks
+
+- `src/catalog/public-contract.spec.ts` downloads the public contract published by [`PatrolTech/sdk-api`](https://github.com/PatrolTech/sdk-api) at the tag of the installed SDK version (`v<version>/openapi/openapi.public.json`) and checks that every `operationId` of every capability exists there and as a function of `@patroltech/sdk-api`. Offline, point `PATROLTECH_PUBLIC_CONTRACT` to a local copy of that file.
+- Dependabot opens a pull request for every new SDK version; CI runs that check on it.
+
+### Known contract gaps
+
+Calls made with `sdkFetch` and the SDK URL builder because the contract does not declare a query parameter the API needs yet:
+
+| operationId                   | Call                                                            | Missing in the contract                |
+| ----------------------------- | --------------------------------------------------------------- | -------------------------------------- |
+| `getIncidentDetail`           | `GET /api/features/incident-reporting/incidents/{id}`           | query `locationId` or `organizationId` |
+| `updateIncidentStatus`        | `PATCH /api/features/incident-reporting/incidents/{id}/status`  | same                                   |
+| `assignIncident`              | `PATCH /api/features/incident-reporting/incidents/{id}/assign`  | same                                   |
+| `addIncidentComment`          | `POST /api/features/incident-reporting/incidents/{id}/comments` | same                                   |
+| `createCheckoutSession`       | `POST /api/payments/checkout-session`                           | query `organizationId`                 |
+| `createCustomerPortalSession` | `POST /api/payments/customer-portal`                            | same                                   |
+
+Types completed by hand where the contract is loose:
+
+| operationId                           | Gap                                                                 | Local type                                               |
+| ------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
+| `getRouteRounds`                      | Each round is a free-form object.                                   | `RouteRoundItem`                                         |
+| `getIncidentDetail`                   | `media[].type` (`PHOTO`/`VIDEO`) is not declared.                   | `IncidentDetailItem`                                     |
+| `listCheckpoints`, `createCheckpoint` | `createdAt` is not declared; `fraudRules` may arrive as JSON text.  | `CheckpointItem`, `RawFraudRules`                        |
+| `getLicenseInfo`, `getPaymentPrices`  | The nullable `allOf` generated by orval loses `null`.               | Read as `LicenseUsage \| null` / `PlanPricing \| null`   |
+| `getLicenseInfo`                      | Whether the organization already pays a subscription is not public. | `PlanUsage.pagaSuscripcion` is always `null` (see below) |
+| `createOrganizationUser`              | `meta.emailSent` (outside `data`) is not declared.                  | Defensive read of `meta`                                 |
+
+Because the public contract does not say whether an organization already pays, the checkout link capability relies on the API: when it refuses a second subscription (`409 ALREADY_SUBSCRIBED`), the capability returns the customer portal link instead.
+
+## Development
+
+```bash
+npm ci
+npm run format:check
+npm run lint
+npm test            # needs network access to read the published contract
+npm run build
+```
+
+Contributions are welcome through pull requests. Security issues: see [SECURITY.md](./SECURITY.md); never include credentials, tokens or customer data in issues.
+
+## Related
+
+- [`@patroltech/sdk-api`](https://github.com/PatrolTech/sdk-api): the TypeScript SDK and the public OpenAPI contract, with the OAuth 2.1 flow.
+- [PatrolTech MCP connector](https://mcp.patroltech.online/mcp) and its client configurations in [`PatrolTech/ai-integrations`](https://github.com/PatrolTech/ai-integrations).
+
+## About PatrolTech
+
+PatrolTech is guard tour and security patrol software developed by Ingenieros Web SL in Madrid, Spain: QR/NFC checkpoint recording, offline patrol records, incident reports and a management dashboard. [patroltech.online](https://patroltech.online/en)
+
+## License
+
+[MIT](./LICENSE) © Ingenieros Web SL

package/dist/actions/alerts.d.ts

@@ -0,0 +1,3 @@
+import { type ActionDefinition, type ActionEnv } from './types.js';
+export declare function setAlertPreference({ gateway }: ActionEnv): ActionDefinition;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/actions/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../src/actions/alerts.ts"],"names":[],"mappings":"AAQA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAgDpF,wBAAgB,kBAAkB,CAAC,EAAE,OAAO,EAAE,EAAE,SAAS,GAAG,gBAAgB,CAkD3E"}

package/dist/actions/alerts.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { segunIdioma } from '../domain/language.js';
+import { ALERT_CHANNELS, ALERT_TYPES, } from '../gateway/index.js';
+import { defineBotAction } from './types.js';
+/** Activar o desactivar una alerta del propio usuario. */
+/** Nombre de cada alerta tal como sale en «Preferencias de notificaciones» del panel. */
+const ALERT_LABELS = {
+    pending_route: { es: 'Ruta pendiente', en: 'Pending route', fr: 'Parcours en attente' },
+    missed_route: { es: 'Ruta no completada', en: 'Missed route', fr: 'Parcours non effectué' },
+    upcoming_deadline: { es: 'Fecha límite próxima', en: 'Upcoming deadline', fr: 'Échéance proche' },
+    patroller_inactive: { es: 'Patrullero inactivo', en: 'Inactive patroller', fr: 'Agent inactif' },
+    suspicious_scan: { es: 'Escaneo sospechoso', en: 'Suspicious scan', fr: 'Scan suspect' },
+    role_assignment: { es: 'Asignación de rol', en: 'Role assignment', fr: 'Attribution de rôle' },
+    incident_created: { es: 'Nueva incidencia', en: 'New incident', fr: 'Nouvel incident' },
+    incident_status_changed: {
+        es: 'Estado de incidencia cambiado',
+        en: 'Incident status changed',
+        fr: "Statut d'incident modifié",
+    },
+    incident_assigned: { es: 'Incidencia asignada', en: 'Incident assigned', fr: 'Incident assigné' },
+    incident_comment: {
+        es: 'Comentario en incidencia',
+        en: 'Incident comment',
+        fr: 'Commentaire sur un incident',
+    },
+};
+const CHANNEL_LABELS = {
+    email: 'email',
+    push: 'push',
+    whatsapp: 'WhatsApp',
+};
+/** Tipos sin canal WhatsApp en el registro de alertas del backend (`availableChannels`). */
+const SIN_WHATSAPP = ['incident_assigned', 'incident_comment'];
+const alertParams = {
+    tipo: z
+        .enum(ALERT_TYPES)
+        .describe('Tipo de alerta: pending_route = Ruta pendiente; missed_route = Ruta no completada; upcoming_deadline = Fecha límite próxima; ' +
+        'patroller_inactive = Patrullero inactivo; suspicious_scan = Escaneo sospechoso; role_assignment = Asignación de rol; ' +
+        'incident_created = Nueva incidencia; incident_status_changed = Estado de incidencia cambiado; incident_assigned = Incidencia asignada; ' +
+        'incident_comment = Comentario en incidencia'),
+    canal: z.enum(ALERT_CHANNELS).describe('Canal: email, push o whatsapp'),
+    activar: z
+        .boolean()
+        .describe('true = empezar a recibirla por ese canal; false = dejar de recibirla'),
+};
+export function setAlertPreference({ gateway }) {
+    return defineBotAction({
+        nombre: 'set_alert_preference',
+        tool: 'proponer_cambiar_alerta',
+        descripcion: 'Prepara activar o desactivar UNA alerta del propio usuario por un canal (email, push o WhatsApp). Solo cambia sus avisos, ' +
+            'no los de otros usuarios. NO lo cambia: le envía un resumen con un botón para confirmarlo. Úsala cuando el cliente quiera ' +
+            'dejar de recibir o empezar a recibir un aviso. Para varios cambios, llámala una vez por cada uno en el MISMO turno: van juntos en una sola confirmación. ' +
+            'Por WhatsApp solo llegan de verdad Ruta no completada, Patrullero inactivo y Escaneo sospechoso.',
+        params: alertParams,
+        rolMinimo: 'VIEWER',
+        async preparar(_ctx, p) {
+            if (p.canal === 'whatsapp' && SIN_WHATSAPP.includes(p.tipo)) {
+                return {
+                    error: `La alerta «${ALERT_LABELS[p.tipo].es}» no tiene canal WhatsApp: solo email y push.`,
+                };
+            }
+            return { params: p };
+        },
+        resumen(p, { idioma }) {
+            const alerta = ALERT_LABELS[p.tipo][idioma];
+            const canal = CHANNEL_LABELS[p.canal];
+            return segunIdioma(idioma, {
+                es: `${p.activar ? 'Activar' : 'Desactivar'} la alerta «${alerta}» por ${canal} para tu usuario. ` +
+                    'Solo te afecta a ti, en todas tus organizaciones; no cambia los avisos de nadie más.',
+                en: `${p.activar ? 'Turn on' : 'Turn off'} the «${alerta}» alert by ${canal} for your user. ` +
+                    'It only affects you, in all your organizations; nobody else’s notices change.',
+                fr: `${p.activar ? 'Activer' : 'Désactiver'} l'alerte «${alerta}» par ${canal} pour votre utilisateur. ` +
+                    'Cela ne concerne que vous, dans toutes vos organisations ; les avis des autres ne changent pas.',
+            });
+        },
+        async ejecutar(ctx, p) {
+            await gateway.setAlertPreference({ tipo: p.tipo, canal: p.canal, activar: p.activar }, ctx.token);
+            const alerta = ALERT_LABELS[p.tipo][ctx.language];
+            const canal = CHANNEL_LABELS[p.canal];
+            return {
+                texto: segunIdioma(ctx.language, {
+                    es: `✅ Hecho: la alerta «${alerta}» por ${canal} queda ${p.activar ? 'activada' : 'desactivada'} para tu usuario.`,
+                    en: `✅ Done: the «${alerta}» alert by ${canal} is now ${p.activar ? 'on' : 'off'} for your user.`,
+                    fr: `✅ C'est fait : l'alerte «${alerta}» par ${canal} est maintenant ${p.activar ? 'activée' : 'désactivée'} pour votre utilisateur.`,
+                }),
+            };
+        },
+    });
+}
+//# sourceMappingURL=alerts.js.map

package/dist/actions/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../../src/actions/alerts.ts"],"names":[],"mappings":"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"}

package/dist/actions/batch-policy.d.ts

@@ -0,0 +1,67 @@
+import type { ActionDefinition } from './types.js';
+/**
+ * Reglas de negocio de un lote de propuestas (las de UN turno, que salen juntas
+ * en una sola confirmación), sacadas del colector del bot (`collectProposals`)
+ * para que el bot y el servidor MCP apliquen exactamente las mismas.
+ *
+ * Funciones puras sobre un estado inmutable: sin BD, sin canal y sin reloj. El
+ * orden de la lista y la serialización de las llamadas concurrentes son del
+ * motor de cada consumidor. Uso por propuesta:
+ * 1. `reservarEnLote` ANTES de preparar (cupo del lote y un borrado por confirmación);
+ * 2. si preparar falla o lanza, `liberarEnLote` (un borrado no preparado no cuenta);
+ * 3. si sale bien, `aceptarEnLote` (descarta la repetida).
+ */
+/** Máximo de acciones en una confirmación: la lista tiene que poder leerse entera antes de pulsar. */
+export declare const MAX_POR_LOTE = 10;
+export declare const LOTE_LLENO = "m\u00E1ximo 10 por confirmaci\u00F3n; prop\u00F3n el resto despu\u00E9s";
+export declare const UN_BORRADO_POR_LOTE = "Solo se puede borrar una ubicaci\u00F3n por confirmaci\u00F3n: prop\u00F3n la siguiente cuando esta est\u00E9 hecha.";
+export declare const REPETIDA: string;
+/** Una propuesta ya preparada, tal como la compara el lote. */
+export interface PropuestaDelLote {
+    definition: Pick<ActionDefinition, 'nombre' | 'huella'>;
+    orgId: string;
+    params: Record<string, unknown>;
+}
+/** Lo que el lote lleva contado en el turno. */
+export interface EstadoDelLote {
+    /**
+     * Huecos ya pedidos en el turno. El hueco de una propuesta rechazada
+     * sigue contando para el máximo; liberarlo desordenaría la lista y, con 10 de
+     * margen, no compensa.
+     */
+    reservas: number;
+    /** Borrados de ubicación reservados o aceptados (como mucho uno). */
+    borrados: number;
+    /** Huellas de las propuestas aceptadas, en orden. */
+    huellas: readonly string[];
+}
+/** El lote al empezar el turno (y tras enviarlo). */
+export declare const LOTE_VACIO: EstadoDelLote;
+type Decision = {
+    ok: true;
+    estado: EstadoDelLote;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Misma acción, organización e identidad: la que define la acción (`huella`) o,
+ * sin ella, todos los parámetros ya preparados (las claves en cualquier orden).
+ */
+export declare function huellaDePropuesta(p: PropuestaDelLote): string;
+/** Antes de preparar: ¿cabe otra propuesta de esta acción en el lote? Si cabe, la reserva. */
+export declare function reservarEnLote(estado: EstadoDelLote, nombre: string): Decision;
+/**
+ * La preparación de una reservada falló o lanzó: un borrado que no llega a
+ * prepararse (nombre mal escrito, backend caído) no cuenta, para que el reintento
+ * corregido del mismo turno se admita. Su hueco sigue contando.
+ */
+export declare function liberarEnLote(estado: EstadoDelLote, nombre: string): EstadoDelLote;
+/**
+ * Tras preparar: la acepta salvo que sea la misma que otra ya aceptada (p. ej.
+ * quitar un acceso dos veces haría fallar la segunda al confirmar, con la primera
+ * ya hecha). Se compara lo preparado: dos formas de nombrar lo mismo son la misma.
+ */
+export declare function aceptarEnLote(estado: EstadoDelLote, propuesta: PropuestaDelLote): Decision;
+export {};
+//# sourceMappingURL=batch-policy.d.ts.map

package/dist/actions/batch-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-policy.d.ts","sourceRoot":"","sources":["../../src/actions/batch-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;GAWG;AAEH,sGAAsG;AACtG,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,eAAO,MAAM,UAAU,4EAAwD,CAAC;AAChF,eAAO,MAAM,mBAAmB,yHACoE,CAAC;AACrG,eAAO,MAAM,QAAQ,QAEkB,CAAC;AAExC,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,qDAAqD;AACrD,eAAO,MAAM,UAAU,EAAE,aAAyD,CAAC;AAEnF,KAAK,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAQnF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAQ7D;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAW9E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAElF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,QAAQ,CAI1F"}

package/dist/actions/batch-policy.js

@@ -0,0 +1,73 @@
+/**
+ * Reglas de negocio de un lote de propuestas (las de UN turno, que salen juntas
+ * en una sola confirmación), sacadas del colector del bot (`collectProposals`)
+ * para que el bot y el servidor MCP apliquen exactamente las mismas.
+ *
+ * Funciones puras sobre un estado inmutable: sin BD, sin canal y sin reloj. El
+ * orden de la lista y la serialización de las llamadas concurrentes son del
+ * motor de cada consumidor. Uso por propuesta:
+ * 1. `reservarEnLote` ANTES de preparar (cupo del lote y un borrado por confirmación);
+ * 2. si preparar falla o lanza, `liberarEnLote` (un borrado no preparado no cuenta);
+ * 3. si sale bien, `aceptarEnLote` (descarta la repetida).
+ */
+/** Máximo de acciones en una confirmación: la lista tiene que poder leerse entera antes de pulsar. */
+export const MAX_POR_LOTE = 10;
+export const LOTE_LLENO = 'máximo 10 por confirmación; propón el resto después';
+export const UN_BORRADO_POR_LOTE = 'Solo se puede borrar una ubicación por confirmación: propón la siguiente cuando esta esté hecha.';
+export const REPETIDA = 'Esta acción ya está propuesta en este turno con los mismos datos (la misma organización, persona, checkpoint…): no la repitas. ' +
+    'Va una sola vez en la confirmación.';
+/** El lote al empezar el turno (y tras enviarlo). */
+export const LOTE_VACIO = { reservas: 0, borrados: 0, huellas: [] };
+/**
+ * Cada borrado de ubicación comprueba «no es la última» por separado: dos en el
+ * mismo lote podrían dejar la organización sin ninguna. Uno por confirmación.
+ */
+const esBorrado = (nombre) => nombre === 'delete_location';
+/**
+ * Misma acción, organización e identidad: la que define la acción (`huella`) o,
+ * sin ella, todos los parámetros ya preparados (las claves en cualquier orden).
+ */
+export function huellaDePropuesta(p) {
+    return JSON.stringify([
+        p.definition.nombre,
+        p.orgId,
+        p.definition.huella
+            ? p.definition.huella(p.params)
+            : Object.entries(p.params).sort(([a], [b]) => a.localeCompare(b)),
+    ]);
+}
+/** Antes de preparar: ¿cabe otra propuesta de esta acción en el lote? Si cabe, la reserva. */
+export function reservarEnLote(estado, nombre) {
+    if (estado.reservas >= MAX_POR_LOTE)
+        return { ok: false, error: LOTE_LLENO };
+    if (esBorrado(nombre) && estado.borrados > 0)
+        return { ok: false, error: UN_BORRADO_POR_LOTE };
+    return {
+        ok: true,
+        estado: {
+            ...estado,
+            reservas: estado.reservas + 1,
+            borrados: estado.borrados + (esBorrado(nombre) ? 1 : 0),
+        },
+    };
+}
+/**
+ * La preparación de una reservada falló o lanzó: un borrado que no llega a
+ * prepararse (nombre mal escrito, backend caído) no cuenta, para que el reintento
+ * corregido del mismo turno se admita. Su hueco sigue contando.
+ */
+export function liberarEnLote(estado, nombre) {
+    return esBorrado(nombre) ? { ...estado, borrados: Math.max(0, estado.borrados - 1) } : estado;
+}
+/**
+ * Tras preparar: la acepta salvo que sea la misma que otra ya aceptada (p. ej.
+ * quitar un acceso dos veces haría fallar la segunda al confirmar, con la primera
+ * ya hecha). Se compara lo preparado: dos formas de nombrar lo mismo son la misma.
+ */
+export function aceptarEnLote(estado, propuesta) {
+    const huella = huellaDePropuesta(propuesta);
+    if (estado.huellas.includes(huella))
+        return { ok: false, error: REPETIDA };
+    return { ok: true, estado: { ...estado, huellas: [...estado.huellas, huella] } };
+}
+//# sourceMappingURL=batch-policy.js.map

package/dist/actions/batch-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-policy.js","sourceRoot":"","sources":["../../src/actions/batch-policy.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,sGAAsG;AACtG,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,qDAAqD,CAAC;AAChF,MAAM,CAAC,MAAM,mBAAmB,GAC9B,kGAAkG,CAAC;AACrG,MAAM,CAAC,MAAM,QAAQ,GACnB,iIAAiI;IACjI,qCAAqC,CAAC;AAuBxC,qDAAqD;AACrD,MAAM,CAAC,MAAM,UAAU,GAAkB,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAInF;;;GAGG;AACH,MAAM,SAAS,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,KAAK,iBAAiB,CAAC;AAE5E;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAmB;IACnD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,CAAC,CAAC,UAAU,CAAC,MAAM;QACnB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,UAAU,CAAC,MAAM;YACjB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;YAC/B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;KACpE,CAAC,CAAC;AACL,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,MAAqB,EAAE,MAAc;IAClE,IAAI,MAAM,CAAC,QAAQ,IAAI,YAAY;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC7E,IAAI,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC/F,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE;YACN,GAAG,MAAM;YACT,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,CAAC;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACxD;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB,EAAE,MAAc;IACjE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB,EAAE,SAA2B;IAC9E,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC3E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;AACnF,CAAC"}

package/dist/actions/checkpoint-archive.d.ts

@@ -0,0 +1,3 @@
+import { type ActionDefinition, type ActionEnv } from './types.js';
+export declare function archiveCheckpoint(env: ActionEnv): ActionDefinition;
+//# sourceMappingURL=checkpoint-archive.d.ts.map

package/dist/actions/checkpoint-archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-archive.d.ts","sourceRoot":"","sources":["../../src/actions/checkpoint-archive.ts"],"names":[],"mappings":"AAWA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAgGpF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,gBAAgB,CA2FlE"}