@hostwebhook/node-types 1.86.0 → 1.88.0

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

@@ -0,0 +1,52 @@
+/**
+ * PostgreSQL AI Toolkit — las herramientas que un postgresAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * ## Por qué las escrituras NO reciben SQL (2026-09-24, decisión de Ariel)
+ *
+ * El nodo, en modo de una operación, ejecuta el SQL que se le escribe: sus
+ * cinco operaciones son una etiqueta encima del mismo SQL crudo. Si el toolkit
+ * hiciera lo mismo, bloquear una herramienta no bloquearía nada — un
+ * `insert_rows` puede llevar un `DELETE` dentro de un `WITH`, y quien bloqueó
+ * `delete_rows` seguiría viendo desaparecer filas.
+ *
+ * Así que las tres escrituras reciben la tabla del nodo y JSON, y el SQL lo
+ * genera el handler, parametrizado y con los identificadores entrecomillados:
+ * el modelo no escribe SQL que se ejecute como escritura.
+ *
+ * ## Lo que queda con SQL, y cómo se contiene
+ *
+ * - `query_rows` recibe SQL, y corre dentro de una transacción **READ ONLY**:
+ *   un `DELETE`, un `UPDATE` o un `CREATE` los rechaza el propio Postgres, no
+ *   una expresión regular nuestra. Puede leer otras tablas —un JOIN hace
+ *   falta a menudo—; el límite ahí lo pone el usuario de base de datos de la
+ *   credencial.
+ * - `execute_sql` recibe SQL cualquiera, DDL incluido. Es la excepción
+ *   consciente a «sólo la tabla del nodo»: SQL crudo no se puede vallar a una
+ *   tabla. La contienen tres cosas: es siempre destructiva (el gate del AI
+ *   Node la para si está encendido), se puede bloquear en el nodo, y el
+ *   usuario de base de datos.
+ *
+ * Los textos van en inglés porque los lee el modelo.
+ */
+import type { PostgresOperation } from './postgres-operations';
+export interface PostgresToolkitParameter {
+    name: string;
+    /** El esquema MCP sólo admite estos tres; lo estructurado viaja como JSON
+     *  en un `string`. */
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface PostgresToolkitSpec {
+    operation: PostgresOperation;
+    label: string;
+    toolName: string;
+    description: string;
+    parameters: PostgresToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas`, no se escribe a mano. */
+    destructive?: boolean;
+}
+export declare const POSTGRES_TOOLKIT_SPECS: PostgresToolkitSpec[];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export declare const POSTGRES_TOOLKIT_BY_TOOL_NAME: Record<string, PostgresToolkitSpec>;

package/dist/esm/postgres-toolkit.js

@@ -0,0 +1,85 @@
+/**
+ * PostgreSQL AI Toolkit — las herramientas que un postgresAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * ## Por qué las escrituras NO reciben SQL (2026-09-24, decisión de Ariel)
+ *
+ * El nodo, en modo de una operación, ejecuta el SQL que se le escribe: sus
+ * cinco operaciones son una etiqueta encima del mismo SQL crudo. Si el toolkit
+ * hiciera lo mismo, bloquear una herramienta no bloquearía nada — un
+ * `insert_rows` puede llevar un `DELETE` dentro de un `WITH`, y quien bloqueó
+ * `delete_rows` seguiría viendo desaparecer filas.
+ *
+ * Así que las tres escrituras reciben la tabla del nodo y JSON, y el SQL lo
+ * genera el handler, parametrizado y con los identificadores entrecomillados:
+ * el modelo no escribe SQL que se ejecute como escritura.
+ *
+ * ## Lo que queda con SQL, y cómo se contiene
+ *
+ * - `query_rows` recibe SQL, y corre dentro de una transacción **READ ONLY**:
+ *   un `DELETE`, un `UPDATE` o un `CREATE` los rechaza el propio Postgres, no
+ *   una expresión regular nuestra. Puede leer otras tablas —un JOIN hace
+ *   falta a menudo—; el límite ahí lo pone el usuario de base de datos de la
+ *   credencial.
+ * - `execute_sql` recibe SQL cualquiera, DDL incluido. Es la excepción
+ *   consciente a «sólo la tabla del nodo»: SQL crudo no se puede vallar a una
+ *   tabla. La contienen tres cosas: es siempre destructiva (el gate del AI
+ *   Node la para si está encendido), se puede bloquear en el nodo, y el
+ *   usuario de base de datos.
+ *
+ * Los textos van en inglés porque los lee el modelo.
+ */
+import { marcarDestructivas } from './clase-de-herramienta.js';
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+const donde = (que) => p('where', `JSON object selecting the rows ${que}: each key is a column and each value the value it must equal, all of them at once, e.g. {"id": 42} or {"status": "pending", "customer_id": 7}. It cannot be empty — an empty condition would touch every row.`);
+const parametros = () => p('params', 'Optional JSON array with the values for the $1, $2… placeholders in the SQL, e.g. ["paid", 100]. Always pass values this way instead of writing them into the SQL.', false);
+export const POSTGRES_TOOLKIT_SPECS = marcarDestructivas([
+    {
+        operation: 'query',
+        label: 'Query rows',
+        toolName: 'query_rows',
+        description: 'Run a read-only SQL query (SELECT, WITH … SELECT) and return its rows, at most 200. It runs inside a READ ONLY transaction: a statement that writes is rejected by the database. Use it for lookups, counts, sums and joins.',
+        parameters: [
+            p('sql', 'The SELECT statement, with $1, $2… placeholders for values, e.g. SELECT * FROM orders WHERE status = $1 LIMIT 20.'),
+            parametros(),
+        ],
+    },
+    {
+        operation: 'insertOne',
+        label: 'Insert rows',
+        toolName: 'insert_rows',
+        description: "Insert one or more rows into this node's table and return them as stored, with the values the database filled in (ids, defaults). It does not check for duplicates.",
+        parameters: [
+            p('rows', 'JSON object with one row, or a JSON array of rows. Keys are column names, e.g. {"name": "Ariel", "email": "a@b.c"}. A key that is not a column makes the call fail.'),
+        ],
+    },
+    {
+        operation: 'update',
+        label: 'Update rows',
+        toolName: 'update_rows',
+        description: "Update the rows of this node's table that match a condition, overwriting the columns you set, and return them after the update. When no row matches it changes nothing.",
+        parameters: [
+            p('set', 'JSON object with the columns to overwrite and their new values, e.g. {"status": "shipped"}.'),
+            donde('to update'),
+        ],
+    },
+    {
+        operation: 'delete',
+        label: 'Delete rows',
+        toolName: 'delete_rows',
+        description: "Delete the rows of this node's table that match a condition and return them as they were. This cannot be undone: when you are not sure which rows match, check with query_rows first.",
+        parameters: [donde('to delete')],
+    },
+    {
+        operation: 'execute',
+        label: 'Execute SQL',
+        toolName: 'execute_sql',
+        description: 'Run any SQL statement — including ones that change the schema (CREATE, ALTER, DROP) — and return what it produces. It is not limited to this node\'s table. Prefer query_rows, insert_rows, update_rows or delete_rows whenever one of them can do the job.',
+        parameters: [
+            p('sql', 'The SQL statement, with $1, $2… placeholders for values.'),
+            parametros(),
+        ],
+    },
+]);
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export const POSTGRES_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(POSTGRES_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/esm/registry.js

@@ -401,6 +401,11 @@ export const NODE_REGISTRY = {
         allStateKey: "allMongoActions",
         color: "#34d399",
         testable: true,
+        /* Modo AI toolkit (2026-09-24): con `aiEnabled` el nodo sólo lo llama un
+           AI Node —como el resto de toolkits—, y una arista del lienzo no le
+           llevaría nada. Hasta que la api y el dashboard le den `aiEnabled`, el
+           campo no existe y esto devuelve `false`: no cambia nada. */
+        isToolOnly: (e) => e.aiEnabled === true,
     },
     postgresAction: {
         type: "postgresAction",
@@ -413,6 +418,11 @@ export const NODE_REGISTRY = {
         allStateKey: "allPostgresActions",
         color: "#336791",
         testable: true,
+        /* Modo AI toolkit (2026-09-24): con `aiEnabled` el nodo sólo lo llama un
+           AI Node —como el resto de toolkits—, y una arista del lienzo no le
+           llevaría nada. Hasta que la api y el dashboard le den `aiEnabled`, el
+           campo no existe y esto devuelve `false`: no cambia nada. */
+        isToolOnly: (e) => e.aiEnabled === true,
     },
     notificationAction: {
         type: "notificationAction",

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

@@ -34,7 +34,8 @@ export interface SheetsToolkitSpec {
     toolName: string;
     description: string;
     parameters: SheetsToolkitParameter[];
-    /** Escribe en la hoja 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 SHEETS_TOOLKIT_SPECS: SheetsToolkitSpec[];

package/dist/esm/sheets-toolkit.js

@@ -19,6 +19,7 @@
  * pueda usarse sin adaptador. Los textos van en inglés porque los lee el modelo
  * y quien mire la lista de herramientas del servidor MCP.
  */
+import { marcarDestructivas } from './clase-de-herramienta.js';
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
 /*
  * La hoja y la pestaña del nodo van como **defecto**, y el modelo puede
@@ -41,14 +42,13 @@ const p = (name, description, required = true, type = 'string') => ({ name, type
 const hoja = () => p('spreadsheetId', "Id of the Google Sheets document — the long chunk of its URL, between /d/ and /edit.");
 const pestana = () => p('sheetName', 'Name of the tab inside the document, exactly as it reads on its tab strip.');
 const fila = (que) => p('row', `JSON object holding ${que}. Keys are the sheet's **header names**, spelled exactly as they appear in its title row: {"Name": "Ariel", "Email": "a@b.c"}. A key that is not a header makes the call fail, so when you do not know the headers, call get_rows first.`);
-export const SHEETS_TOOLKIT_SPECS = [
+export const SHEETS_TOOLKIT_SPECS = marcarDestructivas([
     {
         operation: 'appendRow',
         label: 'Append row',
         toolName: 'append_row',
         description: 'Add a new row at the bottom of the tab. It does not check whether the row already exists — when it might, use append_or_update_row instead so you do not duplicate it.',
         parameters: [fila('the values of the new row'), hoja(), pestana()],
-        destructive: true,
     },
     {
         operation: 'updateRow',
@@ -62,7 +62,6 @@ export const SHEETS_TOOLKIT_SPECS = [
             hoja(),
             pestana(),
         ],
-        destructive: true,
     },
     {
         operation: 'appendOrUpdateRow',
@@ -76,7 +75,6 @@ export const SHEETS_TOOLKIT_SPECS = [
             hoja(),
             pestana(),
         ],
-        destructive: true,
     },
     {
         operation: 'readRange',
@@ -113,9 +111,8 @@ export const SHEETS_TOOLKIT_SPECS = [
          * en el nodo, y la api la aplica.
          */
         parameters: [p('title', 'Name of the new document.')],
-        destructive: true,
     },
-];
+]);
 /** Las herramientas por nombre, para despachar una llamada del modelo. */
 export const SHEETS_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(SHEETS_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
 /**

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

@@ -38,9 +38,8 @@ export interface SlackToolkitSpec {
     /** Descripción (más reglas de uso) que ve el LLM. */
     description: string;
     parameters: SlackToolkitParameter[];
-    /** 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 SLACK_TOOLKIT_SPECS: SlackToolkitSpec[];

package/dist/esm/slack-toolkit.js

@@ -23,8 +23,9 @@
  * y quien mire la lista de herramientas del servidor MCP.
  */
 import { camposDeSlackNoDisponibles, operacionesDeSlackPara, } from './slack-operations.js';
+import { marcarDestructivas } from './clase-de-herramienta.js';
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
-export const SLACK_TOOLKIT_SPECS = [
+export const SLACK_TOOLKIT_SPECS = marcarDestructivas([
     // ── Messages ─────────────────────────────────────────────────────
     {
         operation: 'sendMessage',
@@ -63,7 +64,6 @@ export const SLACK_TOOLKIT_SPECS = [
             p('channel', 'Channel where the message lives.'),
             p('ts', 'Timestamp of the message to delete.'),
         ],
-        destructive: true,
     },
     {
         operation: 'sendEphemeral',
@@ -142,7 +142,6 @@ export const SLACK_TOOLKIT_SPECS = [
             p('name', 'Channel name — lowercase, no spaces, max 80 chars.'),
             p('isPrivate', 'Create a private channel instead of public. Default false.', false, 'boolean'),
         ],
-        destructive: true,
     },
     {
         operation: 'inviteToChannel',
@@ -212,7 +211,7 @@ export const SLACK_TOOLKIT_SPECS = [
             p('threadTs', 'Thread to attach the file to.', false),
         ],
     },
-];
+]);
 export const SLACK_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(SLACK_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
 /**
  * Las herramientas que ofrecerle al modelo con ESTA credencial.

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

@@ -39,6 +39,9 @@ export interface TelegramToolkitSpec {
     /** Descripción (más reglas de uso) que ve el LLM. */
     description: string;
     parameters: TelegramToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
+    destructive?: boolean;
     /**
      * Encabezado de grupo para la lista de la página de detalle. Las filas
      * consecutivas que comparten grupo se pintan bajo un único título, así que el

package/dist/esm/telegram-toolkit.js

@@ -19,6 +19,7 @@
  * usarse sin adaptador. Los textos van en inglés porque los lee el modelo y
  * quien mire la lista de herramientas del servidor MCP.
  */
+import { marcarDestructivas } from './clase-de-herramienta.js';
 const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
 /*
  * `sendAndWaitForResponse` NO está aquí, y es una decisión, no un olvido: la op
@@ -33,7 +34,7 @@ const p = (name, description, required = true, type = 'string') => ({ name, type
  * campo en ninguna de las dos capas, y añadirlo cambiaría cuándo el AI Node pide
  * confirmación. Eso es otra decisión, no parte de mudar el esquema de sitio.
  */
-export const TELEGRAM_TOOLKIT_SPECS = [
+export const TELEGRAM_TOOLKIT_SPECS = marcarDestructivas([
     {
         operation: 'sendMessage',
         label: 'Send message',
@@ -178,6 +179,6 @@ export const TELEGRAM_TOOLKIT_SPECS = [
             p('showAlert', 'Optional. true = modal alert; false (default) = toast notification.', false, 'boolean'),
         ],
     },
-];
+]);
 /** Las herramientas por nombre, para despachar una llamada del modelo. */
 export const TELEGRAM_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(TELEGRAM_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/esm/toolkits.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Los toolkits por tipo de nodo: qué herramientas expone cada nodo en modo
+ * AI toolkit, en un solo sitio.
+ *
+ * ## Para qué (2026-09-24)
+ *
+ * Para que el gate «Block destructive tool calls» del AI Node pueda preguntar
+ * por la OPERACIÓN y no sólo por el nombre. Hasta hoy sólo miraba el nombre
+ * contra unos patrones (`delete_*`, `drop_*`…), así que `update_row` de Sheets
+ * —que pisa una fila— pasaba con el gate encendido. Con esto, la herramienta
+ * que el AI Node guardó al conectar (`nodeRefType` + `operationOverride`) se
+ * resuelve aquí a su operación, y su `destructive` —que sale del verbo, ver
+ * `clase-de-herramienta.ts`— decide.
+ *
+ * ## Lo que falta aquí, a propósito
+ *
+ * WhatsApp y Social siguen con sus specs fuera de este paquete (WhatsApp
+ * escrito a mano en la api y el dashboard; Social armado por entidad desde el
+ * registro de proveedores). Quien consulte este registro tiene que componerlos
+ * por su lado — {@link esOperacionDestructiva} devuelve `null` para ellos, que
+ * significa «no lo sé», no «no es destructiva». Contacts se mudó el
+ * 2026-09-24.
+ *
+ * ## El bloqueo por nodo y la puerta sin herramienta (2026-09-24)
+ *
+ * Abajo viven también las dos reglas que se aplican a TODA llamada a un nodo en
+ * modo toolkit, en un solo sitio para que la api, hw-nodes, node-sdk y el
+ * dashboard pregunten lo mismo:
+ *
+ *   - «Block these tool calls»: el dueño bloquea herramientas en el nodo
+ *     (`blockedTools`, por nombre). Vale para todo tipo de este registro
+ *     ({@link admiteBloqueo}).
+ *   - Sin herramienta no se corre: en modo toolkit un nodo sólo ejecuta la
+ *     herramienta que le nombran en `operation`. Un evento sin ella —una arista
+ *     vieja del lienzo— ya no corre la operación de «Single operation», que en
+ *     ese modo no se ve. Decisión de Ariel para los catorce toolkits
+ *     ({@link TIPOS_CON_TOOLKIT}), no sólo los de este registro.
+ *
+ * {@link motivoParaNoCorrer} junta las dos y la llama node-sdk al registrar
+ * cada handler, así que cubre todo camino que acabe en `handler.execute`.
+ */
+/** Lo mínimo de una herramienta de toolkit que hace falta para decidir. */
+export interface OperacionDeToolkit {
+    operation: string;
+    toolName: string;
+    label: string;
+    destructive?: boolean;
+}
+export declare const TOOLKITS_POR_TIPO: Readonly<Record<string, readonly OperacionDeToolkit[]>>;
+/**
+ * La operación de un toolkit, buscada por su nombre interno (`updateRow`) O
+ * por el nombre de su herramienta (`update_row`).
+ *
+ * Las dos formas porque las dos llegan: el AI Node guarda `operationOverride`
+ * con el nombre interno, y el servidor MCP recibe el nombre de la herramienta.
+ */
+export declare function operacionDeToolkit(nodeType: string | undefined | null, operacionONombre: string | undefined | null): OperacionDeToolkit | null;
+/**
+ * ¿Es destructiva esta operación de toolkit?
+ *
+ * `null` cuando no se sabe —el tipo no es un toolkit de este paquete, o la
+ * operación no existe en él—. Quien llama decide qué hace con el «no sé»; el
+ * gate del AI Node lo combina con los patrones de nombre, que siguen ahí para
+ * las herramientas que no son de toolkit (MCP, HTTP…).
+ */
+export declare function esOperacionDestructiva(nodeType: string | undefined | null, operacionONombre: string | undefined | null): boolean | null;
+/**
+ * Los tipos con modo AI toolkit de VARIAS herramientas: los de este registro
+ * más WhatsApp y Social, cuyas herramientas aún no viven aquí. Es la lista de
+ * quién se niega a correr sin herramienta pedida.
+ *
+ * RSS, Mailchimp o Shopify también tienen `aiEnabled`, pero exponen el nodo
+ * como UNA herramienta sin `operation`: no están aquí a propósito.
+ */
+export declare const TIPOS_CON_TOOLKIT: readonly string[];
+export declare function tieneModoToolkit(nodeType: string | undefined | null): boolean;
+/**
+ * ¿Admite «Block these tool calls»? Los de este registro: para bloquear hay
+ * que saber traducir la operación que guarda el AI Node al nombre de la
+ * herramienta que guarda el nodo, y eso sólo se sabe aquí.
+ */
+export declare function admiteBloqueo(nodeType: string | undefined | null): boolean;
+/** Los nombres de herramienta de un toolkit: lo único que `blockedTools` acepta. */
+export declare function nombresDeHerramientas(nodeType: string | undefined | null): string[];
+/** Los nombres bloqueados de un nodo, tolerando documentos sin el campo. */
+export declare function bloqueadasDe(entidad: unknown): string[];
+/**
+ * ¿Está bloqueada en este nodo? Acepta la operación (`deleteOne`, lo que guarda
+ * el AI Node en `operationOverride`) o el nombre (`delete_document`, lo que
+ * recibe el servidor MCP).
+ */
+export declare function herramientaBloqueadaEn(entidad: unknown, nodeType: string | undefined | null, operacionONombre: string | undefined | null): boolean;
+/** Lo que se contesta a una llamada sin herramienta. Lo lee una persona en el
+ *  historial —una arista vieja— o el modelo, así que dice qué hacer. */
+export declare const MENSAJE_SIN_HERRAMIENTA = "This node is an AI toolkit: it only runs the tool an AI Node or an MCP client names, and this call named none. If a connection in the flow leads here, remove it \u2014 in toolkit mode the node is not part of the pipeline.";
+export declare function mensajeDeHerramientaBloqueada(toolName: string): string;
+/**
+ * Por qué una llamada NO debe correr en este nodo, o `null` si puede.
+ *
+ * Sólo mira nodos en modo toolkit (`aiEnabled` y un tipo de
+ * {@link TIPOS_CON_TOOLKIT}); cualquier otro nodo corre como siempre. En modo
+ * toolkit:
+ *   - sin `operation` → {@link MENSAJE_SIN_HERRAMIENTA};
+ *   - con una herramienta bloqueada en el nodo → su mensaje.
+ *
+ * Una operación que el registro no conoce NO se rechaza aquí: cada servicio
+ * sabe qué operaciones acepta (Mongo y Postgres las validan con más detalle),
+ * y rechazar lo desconocido aquí rompería operaciones legítimas que no son
+ * herramientas.
+ */
+export declare function motivoParaNoCorrer(nodeType: string | undefined | null, entidad: unknown, payload: unknown): string | null;

package/dist/esm/toolkits.js

@@ -0,0 +1,178 @@
+/**
+ * Los toolkits por tipo de nodo: qué herramientas expone cada nodo en modo
+ * AI toolkit, en un solo sitio.
+ *
+ * ## Para qué (2026-09-24)
+ *
+ * Para que el gate «Block destructive tool calls» del AI Node pueda preguntar
+ * por la OPERACIÓN y no sólo por el nombre. Hasta hoy sólo miraba el nombre
+ * contra unos patrones (`delete_*`, `drop_*`…), así que `update_row` de Sheets
+ * —que pisa una fila— pasaba con el gate encendido. Con esto, la herramienta
+ * que el AI Node guardó al conectar (`nodeRefType` + `operationOverride`) se
+ * resuelve aquí a su operación, y su `destructive` —que sale del verbo, ver
+ * `clase-de-herramienta.ts`— decide.
+ *
+ * ## Lo que falta aquí, a propósito
+ *
+ * WhatsApp y Social siguen con sus specs fuera de este paquete (WhatsApp
+ * escrito a mano en la api y el dashboard; Social armado por entidad desde el
+ * registro de proveedores). Quien consulte este registro tiene que componerlos
+ * por su lado — {@link esOperacionDestructiva} devuelve `null` para ellos, que
+ * significa «no lo sé», no «no es destructiva». Contacts se mudó el
+ * 2026-09-24.
+ *
+ * ## El bloqueo por nodo y la puerta sin herramienta (2026-09-24)
+ *
+ * Abajo viven también las dos reglas que se aplican a TODA llamada a un nodo en
+ * modo toolkit, en un solo sitio para que la api, hw-nodes, node-sdk y el
+ * dashboard pregunten lo mismo:
+ *
+ *   - «Block these tool calls»: el dueño bloquea herramientas en el nodo
+ *     (`blockedTools`, por nombre). Vale para todo tipo de este registro
+ *     ({@link admiteBloqueo}).
+ *   - Sin herramienta no se corre: en modo toolkit un nodo sólo ejecuta la
+ *     herramienta que le nombran en `operation`. Un evento sin ella —una arista
+ *     vieja del lienzo— ya no corre la operación de «Single operation», que en
+ *     ese modo no se ve. Decisión de Ariel para los catorce toolkits
+ *     ({@link TIPOS_CON_TOOLKIT}), no sólo los de este registro.
+ *
+ * {@link motivoParaNoCorrer} junta las dos y la llama node-sdk al registrar
+ * cada handler, así que cubre todo camino que acabe en `handler.execute`.
+ */
+import { GMAIL_ALL_TOOLKIT_SPECS, NATIVE_EMAIL_TOOLKIT_SPECS } from './gmail-operations.js';
+import { GOOGLE_CALENDAR_TOOLKIT_SPECS } from './calendar-toolkit.js';
+import { DRIVE_TOOLKIT_SPECS } from './drive-toolkit.js';
+import { TELEGRAM_TOOLKIT_SPECS } from './telegram-toolkit.js';
+import { DISCORD_TOOLKIT_SPECS } from './discord-toolkit.js';
+import { SLACK_TOOLKIT_SPECS } from './slack-toolkit.js';
+import { SHEETS_TOOLKIT_SPECS } from './sheets-toolkit.js';
+import { DOCS_TOOLKIT_SPECS } from './docs-toolkit.js';
+import { MONGO_TOOLKIT_SPECS } from './mongo-toolkit.js';
+import { POSTGRES_TOOLKIT_SPECS } from './postgres-toolkit.js';
+import { GOOGLE_CONTACTS_TOOLKIT_SPECS } from './google-contacts-toolkit.js';
+export const TOOLKITS_POR_TIPO = Object.freeze({
+    gmailAction: GMAIL_ALL_TOOLKIT_SPECS,
+    emailAction: NATIVE_EMAIL_TOOLKIT_SPECS,
+    calendarAction: GOOGLE_CALENDAR_TOOLKIT_SPECS,
+    driveAction: DRIVE_TOOLKIT_SPECS,
+    telegramAction: TELEGRAM_TOOLKIT_SPECS,
+    discordAction: DISCORD_TOOLKIT_SPECS,
+    slackAction: SLACK_TOOLKIT_SPECS,
+    sheetsAction: SHEETS_TOOLKIT_SPECS,
+    docsAction: DOCS_TOOLKIT_SPECS,
+    mongoAction: MONGO_TOOLKIT_SPECS,
+    postgresAction: POSTGRES_TOOLKIT_SPECS,
+    googleContactsAction: GOOGLE_CONTACTS_TOOLKIT_SPECS,
+});
+/**
+ * La operación de un toolkit, buscada por su nombre interno (`updateRow`) O
+ * por el nombre de su herramienta (`update_row`).
+ *
+ * Las dos formas porque las dos llegan: el AI Node guarda `operationOverride`
+ * con el nombre interno, y el servidor MCP recibe el nombre de la herramienta.
+ */
+export function operacionDeToolkit(nodeType, operacionONombre) {
+    if (!nodeType || !operacionONombre)
+        return null;
+    const toolkit = TOOLKITS_POR_TIPO[nodeType];
+    if (!toolkit)
+        return null;
+    return (toolkit.find((s) => s.operation === operacionONombre) ??
+        toolkit.find((s) => s.toolName === operacionONombre) ??
+        null);
+}
+/**
+ * ¿Es destructiva esta operación de toolkit?
+ *
+ * `null` cuando no se sabe —el tipo no es un toolkit de este paquete, o la
+ * operación no existe en él—. Quien llama decide qué hace con el «no sé»; el
+ * gate del AI Node lo combina con los patrones de nombre, que siguen ahí para
+ * las herramientas que no son de toolkit (MCP, HTTP…).
+ */
+export function esOperacionDestructiva(nodeType, operacionONombre) {
+    const op = operacionDeToolkit(nodeType, operacionONombre);
+    return op ? op.destructive === true : null;
+}
+/* ── Quién tiene toolkit, el bloqueo por nodo y la puerta ───────────────── */
+/**
+ * Los tipos con modo AI toolkit de VARIAS herramientas: los de este registro
+ * más WhatsApp y Social, cuyas herramientas aún no viven aquí. Es la lista de
+ * quién se niega a correr sin herramienta pedida.
+ *
+ * RSS, Mailchimp o Shopify también tienen `aiEnabled`, pero exponen el nodo
+ * como UNA herramienta sin `operation`: no están aquí a propósito.
+ */
+export const TIPOS_CON_TOOLKIT = Object.freeze([
+    ...Object.keys(TOOLKITS_POR_TIPO),
+    'whatsappAction',
+    'socialMediaAction',
+]);
+export function tieneModoToolkit(nodeType) {
+    return !!nodeType && TIPOS_CON_TOOLKIT.includes(nodeType);
+}
+/**
+ * ¿Admite «Block these tool calls»? Los de este registro: para bloquear hay
+ * que saber traducir la operación que guarda el AI Node al nombre de la
+ * herramienta que guarda el nodo, y eso sólo se sabe aquí.
+ */
+export function admiteBloqueo(nodeType) {
+    return !!nodeType && Object.prototype.hasOwnProperty.call(TOOLKITS_POR_TIPO, nodeType);
+}
+/** Los nombres de herramienta de un toolkit: lo único que `blockedTools` acepta. */
+export function nombresDeHerramientas(nodeType) {
+    if (!admiteBloqueo(nodeType))
+        return [];
+    return TOOLKITS_POR_TIPO[nodeType].map((s) => s.toolName);
+}
+/** Los nombres bloqueados de un nodo, tolerando documentos sin el campo. */
+export function bloqueadasDe(entidad) {
+    const lista = entidad?.blockedTools;
+    return Array.isArray(lista) ? lista.filter((x) => typeof x === 'string') : [];
+}
+/**
+ * ¿Está bloqueada en este nodo? Acepta la operación (`deleteOne`, lo que guarda
+ * el AI Node en `operationOverride`) o el nombre (`delete_document`, lo que
+ * recibe el servidor MCP).
+ */
+export function herramientaBloqueadaEn(entidad, nodeType, operacionONombre) {
+    if (!operacionONombre)
+        return false;
+    const bloqueadas = bloqueadasDe(entidad);
+    if (bloqueadas.length === 0)
+        return false;
+    const op = operacionDeToolkit(nodeType, operacionONombre);
+    return bloqueadas.includes(op?.toolName ?? operacionONombre);
+}
+/** Lo que se contesta a una llamada sin herramienta. Lo lee una persona en el
+ *  historial —una arista vieja— o el modelo, así que dice qué hacer. */
+export const MENSAJE_SIN_HERRAMIENTA = 'This node is an AI toolkit: it only runs the tool an AI Node or an MCP client names, and this call named none. If a connection in the flow leads here, remove it — in toolkit mode the node is not part of the pipeline.';
+export function mensajeDeHerramientaBloqueada(toolName) {
+    return `The tool "${toolName}" is blocked on this node by its owner. Do not retry it; tell the user it is not allowed here.`;
+}
+/**
+ * Por qué una llamada NO debe correr en este nodo, o `null` si puede.
+ *
+ * Sólo mira nodos en modo toolkit (`aiEnabled` y un tipo de
+ * {@link TIPOS_CON_TOOLKIT}); cualquier otro nodo corre como siempre. En modo
+ * toolkit:
+ *   - sin `operation` → {@link MENSAJE_SIN_HERRAMIENTA};
+ *   - con una herramienta bloqueada en el nodo → su mensaje.
+ *
+ * Una operación que el registro no conoce NO se rechaza aquí: cada servicio
+ * sabe qué operaciones acepta (Mongo y Postgres las validan con más detalle),
+ * y rechazar lo desconocido aquí rompería operaciones legítimas que no son
+ * herramientas.
+ */
+export function motivoParaNoCorrer(nodeType, entidad, payload) {
+    const e = entidad;
+    if (!e || e.aiEnabled !== true || !tieneModoToolkit(nodeType))
+        return null;
+    const pedida = payload?.operation;
+    if (typeof pedida !== 'string' || !pedida.trim())
+        return MENSAJE_SIN_HERRAMIENTA;
+    if (herramientaBloqueadaEn(entidad, nodeType, pedida)) {
+        const op = operacionDeToolkit(nodeType, pedida);
+        return mensajeDeHerramientaBloqueada(op?.toolName ?? pedida);
+    }
+    return null;
+}

package/dist/gmail-operations.d.ts

@@ -151,6 +151,8 @@ export interface GmailToolkitSpec {
     toolName: string;
     description: string;
     parameters: GmailToolkitParameter[];
+    /** 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 GMAIL_TOOLKIT_SPECS: GmailToolkitSpec[];