@matatbread/matbot-triggers 0.2.9 → 0.3.1

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.9",
+  "version": "0.3.1",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -33,11 +33,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@matatbread/matbot-plugin-api": "^0.2.9"
+    "@matatbread/matbot-plugin-api": "^0.3.1"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "@matatbread/matbot-plugin-api": "^0.2.9"
+    "@matatbread/matbot-plugin-api": "^0.3.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/tools.ts

@@ -1,24 +1,26 @@
-import type { Tool, ToolExecutor, ToolResult, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
 import type { TriggerManager } from './manager.js';
 import type { TriggerCondition, TriggerKind, Trigger } from './types.js';
 
 declare module '@matatbread/matbot-plugin-api' {
-  interface ToolResults {
+  interface ToolContracts {
     // One arm per action: a caller of `invokeTool(machine, 'trigger_action', { action: '…' })` gets the
-    // matching result narrowed by the `action` it passed (see ToolResult / the multi-action note on ToolResults).
+    // matching result narrowed by the `action` it passed (see ToolContract / the multi-action note on ToolContracts).
     trigger_action:
-      | ToolResult<{ triggers: Trigger[] }, { action: 'list'   }>
-      | ToolResult<{ triggers: Trigger[] }, { action: 'query'  }>
-      | ToolResult<Trigger,                 { action: 'get'    }>
-      | ToolResult<{ id: string },          { action: 'add'    }>
-      | ToolResult<Trigger,                 { action: 'update' }>
-      | ToolResult<{ id: string },          { action: 'remove' }>
-      | ToolResult<{ triggers: Trigger[] }, { action: 'move'   }>
-      | ToolResult<{ triggers: Trigger[] }, { action: 'copy'   }>;
+      | ToolContract<{ triggers: Trigger[] }, { action: 'list' }>
+      | ToolContract<{ triggers: Trigger[] }, { action: 'query'; tool?: string; params?: object }>
+      | ToolContract<Trigger,                 { action: 'get'; id: string }>
+      | ToolContract<{ id: string },          { action: 'add'; conditions: TriggerCondition[]; tool: string; params?: object; enabled?: boolean }>
+      | ToolContract<Trigger,                 { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean }>
+      | ToolContract<Trigger,                 { action: 'disable'; id: string }>
+      | ToolContract<Trigger,                 { action: 'enable'; id: string }>
+      | ToolContract<{ id: string },          { action: 'remove'; id: string }>
+      | ToolContract<{ triggers: Trigger[] }, { action: 'move'; tool?: string; params?: object; toTool: string; toParams?: object }>
+      | ToolContract<{ triggers: Trigger[] }, { action: 'copy'; tool?: string; params?: object; toTool: string; toParams?: object }>;
     triggers_config:
-      | ToolResult<{ classifierProvider: string | null; available: string[] }, { action: 'get'   }>
-      | ToolResult<{ classifierProvider: string },                             { action: 'set'   }>
-      | ToolResult<{ classifierProvider: null },                               { action: 'clear' }>;
+      | ToolContract<{ classifierProvider: string | null; available: string[] }, { action: 'get' }>
+      | ToolContract<{ classifierProvider: string },                             { action: 'set'; provider: string }>
+      | ToolContract<{ classifierProvider: null },                               { action: 'clear' }>;
   }
 }
 
@@ -59,6 +61,8 @@ type TriggerActionInput =
   | { action: 'get';    id: string }
   | { action: 'add';    conditions: TriggerCondition[]; tool: string; params?: unknown; enabled?: boolean }
   | { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: unknown; enabled?: boolean }
+  | { action: 'disable'; id: string }
+  | { action: 'enable';  id: string }
   | { action: 'remove'; id: string }
   | { action: 'move';   tool?: string; params?: unknown; toTool: string; toParams?: unknown }
   | { action: 'copy';   tool?: string; params?: unknown; toTool: string; toParams?: unknown };
@@ -136,6 +140,19 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           return;
         }
 
+        // Suspend/resume: keep the trigger but flip whether `evaluate` considers it. Less aggressive
+        // than `remove` — the conditions and invocation are preserved, so re-enabling restores it
+        // exactly. The go-to when a trigger fires too eagerly and you want to stop it without losing it.
+        case 'disable':
+        case 'enable': {
+          const { id } = args as Extract<TriggerActionInput, { action: 'disable' | 'enable' }>;
+          if (!id) { yield { type: 'error', message: `action "${args.action}" requires "id".` }; return; }
+          const t = await manager.update(id, { enabled: args.action === 'enable' });
+          if (t === undefined) { yield { type: 'error', message: `Trigger not found: "${id}"` }; return; }
+          yield { type: 'result', value: t };
+          return;
+        }
+
         case 'remove': {
           const { id } = args as Extract<TriggerActionInput, { action: 'remove' }>;
           if (!id) { yield { type: 'error', message: 'action "remove" requires "id".' }; return; }
@@ -177,7 +194,7 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
         }
 
         default:
-          yield { type: 'error', message: `Unknown action "${String(args.action)}". Expected one of: list, query, get, add, update, remove, move, copy.` };
+          yield { type: 'error', message: `Unknown action "${String(args.action)}". Expected one of: list, query, get, add, update, disable, enable, remove, move, copy.` };
       }
     },
   };
@@ -187,25 +204,14 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
     description:
       'Manage triggers — data-driven hooks that invoke a tool when an LLM classifier judges one of ' +
       'their conditions matched against the current turn. Use this to list triggers, find the ones ' +
-      'that invoke a given tool (query), read one, create one, edit one by id, delete one, or bulk ' +
-      're-target a selected set onto a new tool — in place (move) or as duplicates (copy).\n\n' +
+      'that invoke a given tool (query), read one, create one, edit one by id, suspend one so it stops ' +
+      'firing while keeping it (disable) or bring it back (enable), delete one, or bulk re-target a ' +
+      'selected set onto a new tool — in place (move) or as duplicates (copy).\n\n' +
+      'When a trigger fires too eagerly, prefer "disable" over "remove": it keeps the conditions and ' +
+      'invocation intact (so "enable" restores it exactly) but excludes it from evaluation entirely.\n\n' +
       GUIDANCE + '\n\n' +
       'A trigger has a stable `id` — address it by that, never by its conditions. To change one, ' +
       '"get" or "list" first to read the id, then "update" by id.\n\n' +
-      'Parameters depend on `action` (TypeScript):\n' +
-      '```ts\n' +
-      "type TriggerKind = 'ephemeral' | 'contextual' | 'retract' | 'followup';  // ephemeral=judge user msg+inject for this turn; contextual=judge user msg+fold durably onto it; retract=wrong, redo; followup=stands, add steer turn\n" +
-      'type TriggerCondition = { kind: TriggerKind; rule: string };\n' +
-      'type TriggerAction =\n' +
-      "  | { action: 'list' }                                                              // -> { triggers: [...] }\n" +
-      "  | { action: 'query';  tool?: string; params?: object }                            // triggers invoking that tool -> { triggers: [...] }\n" +
-      "  | { action: 'get';    id: string }                                                // -> the trigger\n" +
-      "  | { action: 'add';    conditions: TriggerCondition[]; tool: string; params?: object; enabled?: boolean }  // -> { id }\n" +
-      "  | { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean }  // edit by id\n" +
-      "  | { action: 'remove'; id: string }                                                // -> { id }\n" +
-      "  | { action: 'move';   tool?: string; params?: object; toTool: string; toParams?: object }   // re-target the queried set's invoke to toTool/toParams in place -> { triggers: [...] }\n" +
-      "  | { action: 'copy';   tool?: string; params?: object; toTool: string; toParams?: object };  // duplicate the queried set, the copies invoking toTool/toParams -> { triggers: [...] }\n" +
-      '```\n\n' +
       'For `move`/`copy`, `tool`/`params` are the SAME selector as `query` (they pick which triggers ' +
       'to act on); `toTool`/`toParams` are the new invocation. A filter is required — both refuse to ' +
       'act on the entire trigger set.',
@@ -213,15 +219,15 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
       type:       'object',
       required:   ['action'],
       properties: {
-        action:     { type: 'string', enum: ['list', 'query', 'get', 'add', 'update', 'remove', 'move', 'copy'], description: 'The operation to perform.' },
-        id:         { type: 'string', description: 'Trigger id. Required for get/update/remove.' },
+        action:     { type: 'string', enum: ['list', 'query', 'get', 'add', 'update', 'disable', 'enable', 'remove', 'move', 'copy'], description: 'The operation to perform.' },
+        id:         { type: 'string', description: 'Trigger id. Required for get/update/disable/enable/remove.' },
         conditions: { type: 'array', description: 'Conditions [{ kind: "ephemeral"|"contextual"|"retract"|"followup", rule: string }]. Required for add.',
           items: { type: 'object', properties: { kind: { type: 'string', enum: ['ephemeral', 'contextual', 'retract', 'followup'] }, rule: { type: 'string' } } } },
         tool:       { type: 'string', description: 'For add: the tool to invoke. For query/move/copy: the selector matching invoke.tool.' },
         params:     { type: 'object', description: 'For add: params passed verbatim as the invoked tool\'s input. For query/move/copy: the selector matching invoke.params.' },
         toTool:     { type: 'string', description: 'New tool the selected triggers should invoke. Required for move/copy.' },
         toParams:   { type: 'object', description: 'New params for the selected triggers\' invocation (move/copy).' },
-        enabled:    { type: 'boolean', description: 'Set false to keep but disable the trigger.' },
+        enabled:    { type: 'boolean', description: 'On add/update, set false to keep but suspend the trigger (absent ⇒ enabled). To toggle an existing trigger, prefer the dedicated "disable"/"enable" actions.' },
       },
     },
     executor,
@@ -275,14 +281,7 @@ export function createTriggersConfigTool(services: MatbotMachine): Tool<ToolResu
       'provider judges trigger conditions. It is an alias for an existing provider, not a new one. Unset, ' +
       "the classifier uses the current turn's own provider; set it to pin a small/fast model. `get` " +
       'reports the current pin and the available provider names; `set` pins one (it must already be ' +
-      'configured — see the provider tool); `clear` reverts to the turn provider.\n\n' +
-      'Parameters (TypeScript):\n' +
-      '```ts\n' +
-      "type TriggersConfig =\n" +
-      "  | { action: 'get' }                       // -> { classifierProvider: string | null, available }\n" +
-      "  | { action: 'set'; provider: string }     // pin a provider -> { classifierProvider }\n" +
-      "  | { action: 'clear' };                     // revert to the turn provider -> { classifierProvider: null }\n" +
-      '```',
+      'configured — see the provider tool); `clear` reverts to the turn provider.',
     inputSchema: {
       type:       'object',
       required:   ['action'],