@hostwebhook/node-types 1.86.0 → 1.87.0

package/dist/calendar-toolkit.d.ts

@@ -44,6 +44,9 @@ export interface GoogleCalendarToolkitSpec {
     /** Descripción y reglas de uso que ve el LLM. */
     description: string;
     parameters: GoogleCalendarToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
+    destructive?: boolean;
 }
 export declare const GOOGLE_CALENDAR_TOOLKIT_SPECS: GoogleCalendarToolkitSpec[];
 /** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */

package/dist/calendar-toolkit.js

@@ -31,8 +31,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GOOGLE_CALENDAR_TOOLKIT_BY_TOOL_NAME = exports.GOOGLE_CALENDAR_TOOLKIT_SPECS = void 0;
+const clase_de_herramienta_js_1 = require("./clase-de-herramienta.js");
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
-exports.GOOGLE_CALENDAR_TOOLKIT_SPECS = [
+exports.GOOGLE_CALENDAR_TOOLKIT_SPECS = (0, clase_de_herramienta_js_1.marcarDestructivas)([
     {
         operation: "createEvent",
         label: "Create event",
@@ -150,6 +151,6 @@ exports.GOOGLE_CALENDAR_TOOLKIT_SPECS = [
             p("calendarId", "Optional calendar id. Defaults to the configured calendar (usually 'primary'). Use list_my_calendars to discover ids.", false),
         ],
     },
-];
+]);
 /** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
 exports.GOOGLE_CALENDAR_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.GOOGLE_CALENDAR_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/clase-de-herramienta.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Qué le hace al mundo una herramienta, leído de su nombre: la ÚNICA
+ * definición de «destructiva» que comparten el AI Node, el servidor MCP y el
+ * dashboard.
+ *
+ * ## Por qué vive aquí (2026-09-24)
+ *
+ * Había tres definiciones y ninguna coincidía con otra:
+ *
+ *   1. los patrones de nombre del gate del AI Node (`delete_*`, `drop_*`…),
+ *      que es lo ÚNICO que el gate miraba al ejecutar;
+ *   2. el `destructive: true` escrito a mano en cada operación de toolkit, que
+ *      los comentarios decían que usaba el gate y que no leía nadie — y que
+ *      además estaba puesto sin criterio: Docs marcaba `create_doc`, Slack
+ *      `create_slack_channel`, y Gmail no marcaba ni `delete_email`;
+ *   3. la tabla de verbos de las anotaciones MCP de la api, la única con un
+ *      criterio escrito.
+ *
+ * Se queda la tercera, y se sube aquí para que las otras dos la usen. El flag
+ * de cada operación ya no se escribe a mano: lo pone {@link marcarDestructivas}
+ * al cargar el módulo, así que no hay nada que se pueda separar del verbo.
+ *
+ * ## El criterio
+ *
+ *   lectura      no toca nada
+ *   escritura    añade, no pisa           (crear, añadir, enviar…)
+ *   destructiva  pisa o borra algo que ya existía
+ *
+ * Por VERBO —el primer segmento del nombre— y no una lista de cien nombres,
+ * porque los nombres ya son regulares y una lista se queda vieja en cuanto
+ * alguien añade una operación. Las excepciones son los nombres cuyo verbo
+ * miente, cada una con su porqué.
+ */
+export type ClaseDeHerramienta = 'lectura' | 'escritura' | 'destructiva';
+/**
+ * La clase de una herramienta, o `null` si ningún verbo la reconoce.
+ *
+ * El `null` es para las pruebas: una herramienta nueva con un verbo que nadie
+ * conoce tiene que ponerlas en rojo, no colarse clasificada por descuido.
+ */
+export declare function claseDeHerramienta(toolName: string): ClaseDeHerramienta | null;
+/**
+ * ¿Es destructiva? Lo que no se reconoce SE TRATA COMO DESTRUCTIVO: ante una
+ * herramienta que no sabemos qué hace, la respuesta segura para un gate es
+ * pararla, no dejarla pasar.
+ */
+export declare function esHerramientaDestructiva(toolName: string): boolean;
+/**
+ * Pone el `destructive` de cada operación de un toolkit a partir de su nombre.
+ *
+ * Se llama UNA vez, al cargar el módulo de cada toolkit, sobre su propio
+ * array. Muta en sitio a propósito: los `*_BY_TOOL_NAME` y cualquier otro
+ * índice apuntan a los MISMOS objetos, así que ven el flag sin tener que
+ * reconstruirse. `true` cuando es destructiva; cuando no, la clave desaparece
+ * — un `destructive: false` explícito se leería como una decisión que nadie
+ * tomó.
+ */
+export declare function marcarDestructivas<T extends {
+    toolName: string;
+    destructive?: boolean;
+}>(specs: T[]): T[];

package/dist/clase-de-herramienta.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Qué le hace al mundo una herramienta, leído de su nombre: la ÚNICA
+ * definición de «destructiva» que comparten el AI Node, el servidor MCP y el
+ * dashboard.
+ *
+ * ## Por qué vive aquí (2026-09-24)
+ *
+ * Había tres definiciones y ninguna coincidía con otra:
+ *
+ *   1. los patrones de nombre del gate del AI Node (`delete_*`, `drop_*`…),
+ *      que es lo ÚNICO que el gate miraba al ejecutar;
+ *   2. el `destructive: true` escrito a mano en cada operación de toolkit, que
+ *      los comentarios decían que usaba el gate y que no leía nadie — y que
+ *      además estaba puesto sin criterio: Docs marcaba `create_doc`, Slack
+ *      `create_slack_channel`, y Gmail no marcaba ni `delete_email`;
+ *   3. la tabla de verbos de las anotaciones MCP de la api, la única con un
+ *      criterio escrito.
+ *
+ * Se queda la tercera, y se sube aquí para que las otras dos la usen. El flag
+ * de cada operación ya no se escribe a mano: lo pone {@link marcarDestructivas}
+ * al cargar el módulo, así que no hay nada que se pueda separar del verbo.
+ *
+ * ## El criterio
+ *
+ *   lectura      no toca nada
+ *   escritura    añade, no pisa           (crear, añadir, enviar…)
+ *   destructiva  pisa o borra algo que ya existía
+ *
+ * Por VERBO —el primer segmento del nombre— y no una lista de cien nombres,
+ * porque los nombres ya son regulares y una lista se queda vieja en cuanto
+ * alguien añade una operación. Las excepciones son los nombres cuyo verbo
+ * miente, cada una con su porqué.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claseDeHerramienta = claseDeHerramienta;
+exports.esHerramientaDestructiva = esHerramientaDestructiva;
+exports.marcarDestructivas = marcarDestructivas;
+const POR_VERBO = Object.freeze({
+    // Lectura
+    get: 'lectura',
+    list: 'lectura',
+    search: 'lectura',
+    read: 'lectura',
+    download: 'lectura',
+    export: 'lectura',
+    find: 'lectura',
+    /* Los dos de las bases de datos. `query_rows` de Postgres corre dentro de
+       una transacción READ ONLY —no escribe aunque el SQL lo intente— y
+       `aggregate_documents` de Mongo rechaza `$out` y `$merge`, que son las dos
+       etapas que escriben. */
+    query: 'lectura',
+    aggregate: 'lectura',
+    // Escritura que sólo añade
+    send: 'escritura',
+    create: 'escritura',
+    add: 'escritura',
+    append: 'escritura',
+    insert: 'escritura',
+    upload: 'escritura',
+    draft: 'escritura',
+    schedule: 'escritura',
+    reply: 'escritura',
+    forward: 'escritura',
+    invite: 'escritura',
+    share: 'escritura',
+    copy: 'escritura',
+    pin: 'escritura',
+    untrash: 'escritura',
+    mark: 'escritura',
+    answer: 'escritura',
+    /* El par de Calendar: `propose_` crea un evento tentativo sin invitar a
+       nadie, `confirm_` lo promociona y manda las invitaciones. Ninguno pisa
+       nada; mandar invitaciones pesa lo mismo que un `send_email`. */
+    propose: 'escritura',
+    confirm: 'escritura',
+    // Escritura que pisa o borra
+    update: 'destructiva',
+    edit: 'destructiva',
+    replace: 'destructiva',
+    delete: 'destructiva',
+    remove: 'destructiva',
+    trash: 'destructiva',
+    move: 'destructiva',
+    /* `execute_sql` de Postgres: SQL cualquiera, DDL incluido. Siempre
+       destructiva, por decisión de Ariel (2026-09-24). */
+    execute: 'destructiva',
+});
+/**
+ * Los nombres cuyo verbo miente.
+ *
+ * Una entrada aquí es una decisión, y cada una lleva la suya: sin el porqué,
+ * la siguiente persona la quitaría por «incoherente».
+ */
+const EXCEPCIONES = Object.freeze({
+    /* Empieza por `append` y termina pisando la fila que encuentre. */
+    append_or_update_row: 'destructiva',
+    /* Los `batch_*` no dicen en el primer segmento qué hacen: hay que leer el
+       segundo. */
+    batch_create_contacts: 'escritura',
+    batch_update_contacts: 'destructiva',
+    batch_delete_contacts: 'destructiva',
+    /* Compartir no pisa nada, pero expone: un fichero compartido con quien no
+       debía ya ha salido, y eso no se deshace quitando el permiso después. Para
+       un agente que decide solo, pesa como un borrado. */
+    share_drive_file: 'destructiva',
+    /* Añadir un rol no borra nada, pero puede dar permisos de administrador. Es
+       el mismo peso que quitarlo, que ya era destructiva por su verbo. */
+    add_discord_role: 'destructiva',
+});
+/**
+ * La clase de una herramienta, o `null` si ningún verbo la reconoce.
+ *
+ * El `null` es para las pruebas: una herramienta nueva con un verbo que nadie
+ * conoce tiene que ponerlas en rojo, no colarse clasificada por descuido.
+ */
+function claseDeHerramienta(toolName) {
+    const nombre = (toolName ?? '').trim().toLowerCase();
+    if (!nombre)
+        return null;
+    const excepcion = EXCEPCIONES[nombre];
+    if (excepcion)
+        return excepcion;
+    return POR_VERBO[nombre.split('_')[0]] ?? null;
+}
+/**
+ * ¿Es destructiva? Lo que no se reconoce SE TRATA COMO DESTRUCTIVO: ante una
+ * herramienta que no sabemos qué hace, la respuesta segura para un gate es
+ * pararla, no dejarla pasar.
+ */
+function esHerramientaDestructiva(toolName) {
+    const clase = claseDeHerramienta(toolName);
+    return clase === null || clase === 'destructiva';
+}
+/**
+ * Pone el `destructive` de cada operación de un toolkit a partir de su nombre.
+ *
+ * Se llama UNA vez, al cargar el módulo de cada toolkit, sobre su propio
+ * array. Muta en sitio a propósito: los `*_BY_TOOL_NAME` y cualquier otro
+ * índice apuntan a los MISMOS objetos, así que ven el flag sin tener que
+ * reconstruirse. `true` cuando es destructiva; cuando no, la clave desaparece
+ * — un `destructive: false` explícito se leería como una decisión que nadie
+ * tomó.
+ */
+function marcarDestructivas(specs) {
+    for (const spec of specs) {
+        if (esHerramientaDestructiva(spec.toolName))
+            spec.destructive = true;
+        else
+            delete spec.destructive;
+    }
+    return specs;
+}

package/dist/discord-toolkit.d.ts

@@ -38,9 +38,8 @@ export interface DiscordToolkitSpec {
     /** Descripción (más reglas de uso) que ve el LLM. */
     description: string;
     parameters: DiscordToolkitParameter[];
-    /** Operaciones irreversibles o que cambian privilegios. La capa MCP las
-     *  bloquea cuando el nodo de IA lleva `requireConfirmationForDestructive`,
-     *  salvo que la llamada traiga confirmación explícita. */
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
     destructive?: boolean;
 }
 export declare const DISCORD_TOOLKIT_SPECS: DiscordToolkitSpec[];

package/dist/discord-toolkit.js

@@ -27,8 +27,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DISCORD_TOOLKIT_BY_TOOL_NAME = exports.DISCORD_TOOLKIT_SPECS = void 0;
 exports.herramientasDeDiscordPara = herramientasDeDiscordPara;
 const discord_operations_js_1 = require("./discord-operations.js");
+const clase_de_herramienta_js_1 = require("./clase-de-herramienta.js");
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
-exports.DISCORD_TOOLKIT_SPECS = [
+exports.DISCORD_TOOLKIT_SPECS = (0, clase_de_herramienta_js_1.marcarDestructivas)([
     // ── Messages ───────────────────────────────────────────────────
     {
         operation: 'sendMessage',
@@ -67,7 +68,6 @@ exports.DISCORD_TOOLKIT_SPECS = [
             p('channelId', 'Channel snowflake where the message lives.'),
             p('messageId', 'Snowflake of the message to delete.'),
         ],
-        destructive: true,
     },
     {
         operation: 'getMessage',
@@ -153,7 +153,6 @@ exports.DISCORD_TOOLKIT_SPECS = [
         toolName: 'delete_discord_channel',
         description: 'Permanently delete a Discord channel and ALL its messages. Irreversible. ALWAYS confirm with the user before calling — Discord does not provide a recovery window.',
         parameters: [p('channelId', 'Channel snowflake to delete.')],
-        destructive: true,
     },
     {
         operation: 'getChannel',
@@ -209,7 +208,6 @@ exports.DISCORD_TOOLKIT_SPECS = [
             p('userId', 'Member snowflake.'),
             p('roleId', 'Role snowflake to grant.'),
         ],
-        destructive: true,
     },
     {
         operation: 'removeRole',
@@ -221,7 +219,6 @@ exports.DISCORD_TOOLKIT_SPECS = [
             p('userId', 'Member snowflake.'),
             p('roleId', 'Role snowflake to remove.'),
         ],
-        destructive: true,
     },
     {
         operation: 'getMember',
@@ -233,7 +230,7 @@ exports.DISCORD_TOOLKIT_SPECS = [
             p('userId', 'Member snowflake.'),
         ],
     },
-];
+]);
 exports.DISCORD_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.DISCORD_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
 /**
  * Las herramientas que ofrecerle al modelo con ESTA credencial.

package/dist/docs-toolkit.d.ts

@@ -27,7 +27,8 @@ export interface DocsToolkitSpec {
     toolName: string;
     description: string;
     parameters: DocsToolkitParameter[];
-    /** Escribe en el documento del usuario. Lo usa la confirmación previa del AI Node. */
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
     destructive?: boolean;
 }
 export declare const DOCS_TOOLKIT_SPECS: DocsToolkitSpec[];

package/dist/docs-toolkit.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DOCS_TOOLKIT_DEFAULTABLE = exports.DOCS_TOOLKIT_BY_TOOL_NAME = exports.DOCS_TOOLKIT_SPECS = void 0;
+const clase_de_herramienta_js_1 = require("./clase-de-herramienta.js");
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
 /*
  * El documento del nodo va como **defecto** y el modelo puede cambiarlo — la
@@ -34,7 +35,7 @@ const p = (name, description, required = true, type = 'string') => ({ name, type
  * documento nuevo nacería con el id del viejo por título.
  */
 const documento = () => p('documentId', 'Id of the Google Docs document — the long chunk of its URL, between /d/ and /edit.');
-exports.DOCS_TOOLKIT_SPECS = [
+exports.DOCS_TOOLKIT_SPECS = (0, clase_de_herramienta_js_1.marcarDestructivas)([
     {
         operation: 'readDoc',
         label: 'Read document',
@@ -51,7 +52,6 @@ exports.DOCS_TOOLKIT_SPECS = [
             p('title', 'Name of the new document.'),
             p('content', 'Initial body, as HTML. Basic tags work (<p>, <b>, <i>, <ul>, <li>, <h1>…). Plain text is fine too. Leave it out for an empty document.', false),
         ],
-        destructive: true,
     },
     {
         operation: 'appendText',
@@ -62,7 +62,6 @@ exports.DOCS_TOOLKIT_SPECS = [
             p('content', 'What to add, as HTML. Basic tags work (<p>, <b>, <i>, <ul>, <li>, <h1>…). Plain text is fine too.'),
             documento(),
         ],
-        destructive: true,
     },
     {
         operation: 'replaceText',
@@ -74,7 +73,6 @@ exports.DOCS_TOOLKIT_SPECS = [
             p('replaceWith', 'Text to put in its place. An empty string deletes the matches.'),
             documento(),
         ],
-        destructive: true,
     },
     {
         operation: 'insertTable',
@@ -86,9 +84,8 @@ exports.DOCS_TOOLKIT_SPECS = [
             p('cols', 'Number of columns.', true, 'number'),
             documento(),
         ],
-        destructive: true,
     },
-];
+]);
 /** Las herramientas por nombre, para despachar una llamada del modelo. */
 exports.DOCS_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.DOCS_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
 /**

package/dist/drive-toolkit.d.ts

@@ -42,10 +42,15 @@ export interface DriveToolkitSpec {
     /** Encabezado de grupo de la página de detalle. El orden es el que agrupa. */
     group?: string;
     /**
-     * Marca que la herramienta cambia algo difícil de deshacer, para que la página
-     * lo enseñe y el AI Node pida confirmación. Son **dos**, las mismas que ya
-     * estaban marcadas: `delete_drive_file` y `share_drive_file`. `move` no lo
-     * lleva, y es defendible — deshacerlo es otro move.
+     * Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del nombre
+     * (ver `clase-de-herramienta.ts`), no se escribe a mano.
+     *
+     * ⚠️ Hasta el 2026-09-24 aquí se decía que `move` no lo llevaba —«deshacerlo
+     * es otro move»—, mientras la tabla de anotaciones MCP de la api decía lo
+     * contrario: sacar el fichero de su carpeta es quitarlo de donde estaba. Eran
+     * dos criterios para lo mismo; se queda el de la tabla, que es el único que
+     * estaba escrito como regla. `share_drive_file` sigue marcada, ahora como
+     * excepción explícita: compartir expone, y eso no se deshace.
      */
     destructive?: boolean;
 }

package/dist/drive-toolkit.js

@@ -22,11 +22,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DRIVE_TOOLKIT_BY_TOOL_NAME = exports.DRIVE_TOOLKIT_SPECS = void 0;
+const clase_de_herramienta_js_1 = require("./clase-de-herramienta.js");
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
 const ENTRAN_Y_SALEN = 'Files in / out';
 const DESCUBRIR = 'Discovery';
 const MUTACIONES = 'Mutations (LLM confirms first)';
-exports.DRIVE_TOOLKIT_SPECS = [
+exports.DRIVE_TOOLKIT_SPECS = (0, clase_de_herramienta_js_1.marcarDestructivas)([
     /* ── Files in / out ─────────────────────────────────────────────────── */
     {
         operation: 'upload',
@@ -157,7 +158,6 @@ exports.DRIVE_TOOLKIT_SPECS = [
             p('fileId', 'The Drive file ID to delete.'),
             p('permanent', 'Optional. true = bypass trash and erase forever (irreversible). Default false.', false, 'boolean'),
         ],
-        destructive: true,
     },
     {
         operation: 'share',
@@ -173,8 +173,7 @@ exports.DRIVE_TOOLKIT_SPECS = [
             p('domain', 'Required when type=domain.', false),
             p('sendNotificationEmail', 'Optional. true = email the recipient about the share.', false, 'boolean'),
         ],
-        destructive: true,
     },
-];
+]);
 /** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
 exports.DRIVE_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.DRIVE_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/esm/calendar-toolkit.d.ts

@@ -44,6 +44,9 @@ export interface GoogleCalendarToolkitSpec {
     /** Descripción y reglas de uso que ve el LLM. */
     description: string;
     parameters: GoogleCalendarToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
+    destructive?: boolean;
 }
 export declare const GOOGLE_CALENDAR_TOOLKIT_SPECS: GoogleCalendarToolkitSpec[];
 /** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */

package/dist/esm/calendar-toolkit.js

@@ -28,8 +28,9 @@
  * El array se generó desde la copia de la api para que las descripciones largas
  * salieran idénticas, no tecleadas.
  */
+import { marcarDestructivas } from './clase-de-herramienta.js';
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
-export const GOOGLE_CALENDAR_TOOLKIT_SPECS = [
+export const GOOGLE_CALENDAR_TOOLKIT_SPECS = marcarDestructivas([
     {
         operation: "createEvent",
         label: "Create event",
@@ -147,6 +148,6 @@ export const GOOGLE_CALENDAR_TOOLKIT_SPECS = [
             p("calendarId", "Optional calendar id. Defaults to the configured calendar (usually 'primary'). Use list_my_calendars to discover ids.", false),
         ],
     },
-];
+]);
 /** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
 export const GOOGLE_CALENDAR_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(GOOGLE_CALENDAR_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/esm/clase-de-herramienta.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Qué le hace al mundo una herramienta, leído de su nombre: la ÚNICA
+ * definición de «destructiva» que comparten el AI Node, el servidor MCP y el
+ * dashboard.
+ *
+ * ## Por qué vive aquí (2026-09-24)
+ *
+ * Había tres definiciones y ninguna coincidía con otra:
+ *
+ *   1. los patrones de nombre del gate del AI Node (`delete_*`, `drop_*`…),
+ *      que es lo ÚNICO que el gate miraba al ejecutar;
+ *   2. el `destructive: true` escrito a mano en cada operación de toolkit, que
+ *      los comentarios decían que usaba el gate y que no leía nadie — y que
+ *      además estaba puesto sin criterio: Docs marcaba `create_doc`, Slack
+ *      `create_slack_channel`, y Gmail no marcaba ni `delete_email`;
+ *   3. la tabla de verbos de las anotaciones MCP de la api, la única con un
+ *      criterio escrito.
+ *
+ * Se queda la tercera, y se sube aquí para que las otras dos la usen. El flag
+ * de cada operación ya no se escribe a mano: lo pone {@link marcarDestructivas}
+ * al cargar el módulo, así que no hay nada que se pueda separar del verbo.
+ *
+ * ## El criterio
+ *
+ *   lectura      no toca nada
+ *   escritura    añade, no pisa           (crear, añadir, enviar…)
+ *   destructiva  pisa o borra algo que ya existía
+ *
+ * Por VERBO —el primer segmento del nombre— y no una lista de cien nombres,
+ * porque los nombres ya son regulares y una lista se queda vieja en cuanto
+ * alguien añade una operación. Las excepciones son los nombres cuyo verbo
+ * miente, cada una con su porqué.
+ */
+export type ClaseDeHerramienta = 'lectura' | 'escritura' | 'destructiva';
+/**
+ * La clase de una herramienta, o `null` si ningún verbo la reconoce.
+ *
+ * El `null` es para las pruebas: una herramienta nueva con un verbo que nadie
+ * conoce tiene que ponerlas en rojo, no colarse clasificada por descuido.
+ */
+export declare function claseDeHerramienta(toolName: string): ClaseDeHerramienta | null;
+/**
+ * ¿Es destructiva? Lo que no se reconoce SE TRATA COMO DESTRUCTIVO: ante una
+ * herramienta que no sabemos qué hace, la respuesta segura para un gate es
+ * pararla, no dejarla pasar.
+ */
+export declare function esHerramientaDestructiva(toolName: string): boolean;
+/**
+ * Pone el `destructive` de cada operación de un toolkit a partir de su nombre.
+ *
+ * Se llama UNA vez, al cargar el módulo de cada toolkit, sobre su propio
+ * array. Muta en sitio a propósito: los `*_BY_TOOL_NAME` y cualquier otro
+ * índice apuntan a los MISMOS objetos, así que ven el flag sin tener que
+ * reconstruirse. `true` cuando es destructiva; cuando no, la clave desaparece
+ * — un `destructive: false` explícito se leería como una decisión que nadie
+ * tomó.
+ */
+export declare function marcarDestructivas<T extends {
+    toolName: string;
+    destructive?: boolean;
+}>(specs: T[]): T[];

package/dist/esm/clase-de-herramienta.js

@@ -0,0 +1,148 @@
+/**
+ * Qué le hace al mundo una herramienta, leído de su nombre: la ÚNICA
+ * definición de «destructiva» que comparten el AI Node, el servidor MCP y el
+ * dashboard.
+ *
+ * ## Por qué vive aquí (2026-09-24)
+ *
+ * Había tres definiciones y ninguna coincidía con otra:
+ *
+ *   1. los patrones de nombre del gate del AI Node (`delete_*`, `drop_*`…),
+ *      que es lo ÚNICO que el gate miraba al ejecutar;
+ *   2. el `destructive: true` escrito a mano en cada operación de toolkit, que
+ *      los comentarios decían que usaba el gate y que no leía nadie — y que
+ *      además estaba puesto sin criterio: Docs marcaba `create_doc`, Slack
+ *      `create_slack_channel`, y Gmail no marcaba ni `delete_email`;
+ *   3. la tabla de verbos de las anotaciones MCP de la api, la única con un
+ *      criterio escrito.
+ *
+ * Se queda la tercera, y se sube aquí para que las otras dos la usen. El flag
+ * de cada operación ya no se escribe a mano: lo pone {@link marcarDestructivas}
+ * al cargar el módulo, así que no hay nada que se pueda separar del verbo.
+ *
+ * ## El criterio
+ *
+ *   lectura      no toca nada
+ *   escritura    añade, no pisa           (crear, añadir, enviar…)
+ *   destructiva  pisa o borra algo que ya existía
+ *
+ * Por VERBO —el primer segmento del nombre— y no una lista de cien nombres,
+ * porque los nombres ya son regulares y una lista se queda vieja en cuanto
+ * alguien añade una operación. Las excepciones son los nombres cuyo verbo
+ * miente, cada una con su porqué.
+ */
+const POR_VERBO = Object.freeze({
+    // Lectura
+    get: 'lectura',
+    list: 'lectura',
+    search: 'lectura',
+    read: 'lectura',
+    download: 'lectura',
+    export: 'lectura',
+    find: 'lectura',
+    /* Los dos de las bases de datos. `query_rows` de Postgres corre dentro de
+       una transacción READ ONLY —no escribe aunque el SQL lo intente— y
+       `aggregate_documents` de Mongo rechaza `$out` y `$merge`, que son las dos
+       etapas que escriben. */
+    query: 'lectura',
+    aggregate: 'lectura',
+    // Escritura que sólo añade
+    send: 'escritura',
+    create: 'escritura',
+    add: 'escritura',
+    append: 'escritura',
+    insert: 'escritura',
+    upload: 'escritura',
+    draft: 'escritura',
+    schedule: 'escritura',
+    reply: 'escritura',
+    forward: 'escritura',
+    invite: 'escritura',
+    share: 'escritura',
+    copy: 'escritura',
+    pin: 'escritura',
+    untrash: 'escritura',
+    mark: 'escritura',
+    answer: 'escritura',
+    /* El par de Calendar: `propose_` crea un evento tentativo sin invitar a
+       nadie, `confirm_` lo promociona y manda las invitaciones. Ninguno pisa
+       nada; mandar invitaciones pesa lo mismo que un `send_email`. */
+    propose: 'escritura',
+    confirm: 'escritura',
+    // Escritura que pisa o borra
+    update: 'destructiva',
+    edit: 'destructiva',
+    replace: 'destructiva',
+    delete: 'destructiva',
+    remove: 'destructiva',
+    trash: 'destructiva',
+    move: 'destructiva',
+    /* `execute_sql` de Postgres: SQL cualquiera, DDL incluido. Siempre
+       destructiva, por decisión de Ariel (2026-09-24). */
+    execute: 'destructiva',
+});
+/**
+ * Los nombres cuyo verbo miente.
+ *
+ * Una entrada aquí es una decisión, y cada una lleva la suya: sin el porqué,
+ * la siguiente persona la quitaría por «incoherente».
+ */
+const EXCEPCIONES = Object.freeze({
+    /* Empieza por `append` y termina pisando la fila que encuentre. */
+    append_or_update_row: 'destructiva',
+    /* Los `batch_*` no dicen en el primer segmento qué hacen: hay que leer el
+       segundo. */
+    batch_create_contacts: 'escritura',
+    batch_update_contacts: 'destructiva',
+    batch_delete_contacts: 'destructiva',
+    /* Compartir no pisa nada, pero expone: un fichero compartido con quien no
+       debía ya ha salido, y eso no se deshace quitando el permiso después. Para
+       un agente que decide solo, pesa como un borrado. */
+    share_drive_file: 'destructiva',
+    /* Añadir un rol no borra nada, pero puede dar permisos de administrador. Es
+       el mismo peso que quitarlo, que ya era destructiva por su verbo. */
+    add_discord_role: 'destructiva',
+});
+/**
+ * La clase de una herramienta, o `null` si ningún verbo la reconoce.
+ *
+ * El `null` es para las pruebas: una herramienta nueva con un verbo que nadie
+ * conoce tiene que ponerlas en rojo, no colarse clasificada por descuido.
+ */
+export function claseDeHerramienta(toolName) {
+    const nombre = (toolName ?? '').trim().toLowerCase();
+    if (!nombre)
+        return null;
+    const excepcion = EXCEPCIONES[nombre];
+    if (excepcion)
+        return excepcion;
+    return POR_VERBO[nombre.split('_')[0]] ?? null;
+}
+/**
+ * ¿Es destructiva? Lo que no se reconoce SE TRATA COMO DESTRUCTIVO: ante una
+ * herramienta que no sabemos qué hace, la respuesta segura para un gate es
+ * pararla, no dejarla pasar.
+ */
+export function esHerramientaDestructiva(toolName) {
+    const clase = claseDeHerramienta(toolName);
+    return clase === null || clase === 'destructiva';
+}
+/**
+ * Pone el `destructive` de cada operación de un toolkit a partir de su nombre.
+ *
+ * Se llama UNA vez, al cargar el módulo de cada toolkit, sobre su propio
+ * array. Muta en sitio a propósito: los `*_BY_TOOL_NAME` y cualquier otro
+ * índice apuntan a los MISMOS objetos, así que ven el flag sin tener que
+ * reconstruirse. `true` cuando es destructiva; cuando no, la clave desaparece
+ * — un `destructive: false` explícito se leería como una decisión que nadie
+ * tomó.
+ */
+export function marcarDestructivas(specs) {
+    for (const spec of specs) {
+        if (esHerramientaDestructiva(spec.toolName))
+            spec.destructive = true;
+        else
+            delete spec.destructive;
+    }
+    return specs;
+}