@matatbread/matbot-triggers 0.3.7 → 0.4.0

package/package.json

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

package/src/index.ts

@@ -1,4 +1,4 @@
-export type { Trigger, TriggerCondition, TriggerInvoke, TriggerKind, TriggerSurface, TriggerSpec, Triggers, FiredCondition } from './types.js';
+export type { Trigger, TriggerCondition, TriggerCooldown, TriggerInvoke, TriggerKind, TriggerSurface, TriggerSpec, Triggers, FiredCondition } from './types.js';
 export { surfaceOfKind } from './types.js';
 export { TriggerManager }                       from './manager.js';
 export { dispatchTrigger, renderResult }        from './dispatch.js';

package/src/manager.ts

@@ -84,7 +84,8 @@ export class TriggerManager implements Triggers {
       version:    Date.now().toString(),
       conditions: spec.conditions,
       invoke:     spec.invoke,
-      ...(spec.enabled !== undefined ? { enabled: spec.enabled } : {}),
+      ...(spec.enabled  !== undefined ? { enabled:  spec.enabled  } : {}),
+      ...(spec.cooldown !== undefined ? { cooldown: spec.cooldown } : {}),
       createdAt:  now,
       updatedAt:  now,
     };
@@ -100,6 +101,7 @@ export class TriggerManager implements Triggers {
       ...(patch.conditions !== undefined ? { conditions: patch.conditions } : {}),
       ...(patch.invoke     !== undefined ? { invoke:     patch.invoke     } : {}),
       ...(patch.enabled    !== undefined ? { enabled:    patch.enabled    } : {}),
+      ...(patch.cooldown   !== undefined ? { cooldown:   patch.cooldown   } : {}),
       version:   Date.now().toString(),
       updatedAt: new Date().toISOString(),
     }));

package/src/plugin.ts

@@ -3,7 +3,7 @@ import type { MatbotPluginSpec, MatbotMachine, Store, Message, MessageContent, S
 import { TriggerManager } from './manager.js';
 import { dispatchTrigger, renderResult } from './dispatch.js';
 import { createTriggerActionTool, createTriggersConfigTool } from './tools.js';
-import type { Trigger, Triggers, FiredCondition } from './types.js';
+import type { Trigger, Triggers, FiredCondition, TriggerCooldown } from './types.js';
 
 /** A firing trigger's id plus the specific condition(s) that matched — the unit markers trace, so a
  *  post-mortem can see not just that a trigger fired but which rubric the classifier judged true and
@@ -113,7 +113,7 @@ const RETRACTION_CREATOR = 'matbot-retraction';
 // `retractFiredMarker` records which triggers/conditions caused a retract. Both are LLM-invisible
 // diagnostics. The convergence guard reads back BOTH retract-fired AND its own `retract-convergence`
 // suppressions (see retractActiveLastTurn).
-type SuppressCause = 'user-redo' | 'retract-convergence' | 'followup-shadowed';
+type SuppressCause = 'user-redo' | 'retract-convergence' | 'followup-shadowed' | 'cooldown';
 function suppressedMarker(cause: SuppressCause, reason: string, triggers: FiredSource[]): MessageContent {
   return { type: 'marker', creator: 'triggers', data: { event: 'suppressed', cause, reason, triggers } };
 }
@@ -170,6 +170,92 @@ function retractActiveLastTurn(messages: Message[]): Set<string> {
   return ids;
 }
 
+// Every marker event that records a trigger ACTUALLY firing (as opposed to being held off), across both
+// surfaces and all three delivery paths. This is the durable fire log the cool-down is counted from —
+// there is no in-memory counter, so a cool-down holds across restart, reload and a backend swap.
+const FIRE_EVENTS = new Set(['retract-fired', 'followup-fired', 'user-insitu-fired', 'user-retract-fired']);
+
+/** Per-trigger firing history, in turns. `thisTurn` counts fires inside the current turn region (since
+ *  the last genuine user message; a redo or robo resubmit belongs to that same turn). `since` is how
+ *  many genuine user turns ago each trigger last fired — 0 meaning this turn. Absent from `since` ⇒
+ *  never fired in the retained history. */
+interface FireHistory {
+  thisTurn: Map<string, number>;
+  since:    Map<string, number>;
+}
+
+// One backward scan of the message tail, counting genuine (non-robo) user messages as turn boundaries.
+// Deliberately counts only fires, NOT cool-down suppressions: a quiet period is a fixed window that must
+// expire on its own, unlike the retract convergence guard (which re-arms on suppression precisely so a
+// still-matching rule stays held off indefinitely).
+function fireHistory(messages: Message[]): FireHistory {
+  const thisTurn = new Map<string, number>();
+  const since    = new Map<string, number>();
+  let turnsBack  = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!;
+    if (m.role === 'user' && !m.content.every(c => c.origin === 'robo')) { turnsBack++; continue; }
+    for (const c of m.content) {
+      if (c.type !== 'marker' || c.creator !== 'triggers') continue;
+      const d = c.data as { event?: unknown; triggers?: unknown };
+      if (typeof d?.event !== 'string' || !FIRE_EVENTS.has(d.event) || !Array.isArray(d.triggers)) continue;
+      for (const t of d.triggers) {
+        const id = (t as { id?: unknown })?.id;
+        if (typeof id !== 'string') continue;
+        if (!since.has(id)) since.set(id, turnsBack);
+        if (turnsBack === 0) thisTurn.set(id, (thisTurn.get(id) ?? 0) + 1);
+      }
+    }
+  }
+  return { thisTurn, since };
+}
+
+// The second of the two guards that read the same marker stream (see retractActiveLastTurn above),
+// and they are NOT redundant: the convergence guard is a diagnosis — this retract rule did not
+// converge, so hold it until it stops matching, re-arming on its own suppressions so it stays held —
+// while a cool-down is a declared rate, indifferent to whether the rule is well-behaved and expiring
+// on a fixed schedule. One is the machine noticing a defect; the other is an author's policy.
+//
+// The reason a trigger's own cool-down holds it back this turn, or undefined to let it fire. Reported
+// rather than returned as a boolean because a suppression is never silent — the reason lands in the
+// marker, so "why didn't the inner voice fire?" is answerable from the session months later.
+function cooldownHold(cooldown: TriggerCooldown | undefined, id: string, hist: FireHistory): string | undefined {
+  if (!cooldown) return undefined;
+  const { maxPerTurn, quietTurns } = cooldown;
+  if (maxPerTurn !== undefined) {
+    const fired = hist.thisTurn.get(id) ?? 0;
+    if (fired >= maxPerTurn) return `already fired ${fired}× this turn (maxPerTurn ${maxPerTurn})`;
+  }
+  // Counts COMPLETED turns only (`since >= 1`): the quiet period governs later turns, while repeats
+  // within the turn that fired are `maxPerTurn`'s business. Otherwise the two limits would fight —
+  // a quiet period of 1 would make any maxPerTurn above 1 unreachable.
+  if (quietTurns !== undefined && quietTurns > 0) {
+    const since = hist.since.get(id);
+    if (since !== undefined && since >= 1 && since <= quietTurns) {
+      return `fired ${since} turn(s) ago, inside its ${quietTurns}-turn quiet period`;
+    }
+  }
+  return undefined;
+}
+
+/** Split what the classifier fired into the triggers that may act and the suppression markers for
+ *  those their own cool-down holds back. Both phases run this identically — the cool-down governs a
+ *  trigger, not a surface, so the user and agent surfaces share one budget and must share one
+ *  decision. Generic in the fired element so each caller keeps its own extra fields (`kinds`). */
+function applyCooldown<T extends { trigger: Trigger; matched: FiredCondition[] }>(
+  fired: T[],
+  hist:  FireHistory,
+): { kept: T[]; markers: MessageContent[] } {
+  const kept:    T[]              = [];
+  const markers: MessageContent[] = [];
+  for (const f of fired) {
+    const hold = cooldownHold(f.trigger.cooldown, f.trigger.id, hist);
+    if (hold === undefined) kept.push(f);
+    else markers.push(suppressedMarker('cooldown', `trigger held off by its own cool-down: ${hold}`, [{ id: f.trigger.id, matched: f.matched }]));
+  }
+  return { kept, markers };
+}
+
 function textOf(msg: Message | undefined): string {
   return msg?.content.filter(c => c.type === 'text').map(c => c.text).join('\n') ?? '';
 }
@@ -249,7 +335,11 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
     const durableBodies:   string[]         = [];
     const sources:         FiredSource[]    = [];
     const markers:         MessageContent[] = [];
-    for (const { trigger, kinds, matched } of fired) {
+    // A per-trigger cool-down applies to both surfaces: matching says the trigger is relevant, the
+    // cool-down says whether it may act again this soon. Held-off triggers are traced, never silent.
+    const cooled = applyCooldown(fired, fireHistory(ctx.session.messages));
+    markers.push(...cooled.markers);
+    for (const { trigger, kinds, matched } of cooled.kept) {
       const out = await dispatchTrigger(services, trigger, { session: ctx.session, signal: ctx.signal, provider: ctx.provider, ...(ctx.prompt !== undefined ? { prompt: ctx.prompt } : {}) });
       if (out.hadResult) {
         // Contextual dominates: a trigger carrying both kinds folds durable (a superset of ephemeral —
@@ -377,7 +467,17 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
       const followupSources: FiredSource[]    = [];
       const suppressed:      FiredSource[]    = [];
       const markers:         MessageContent[] = [...userOut.markers];
-      for (const { trigger, kinds, matched } of fired) {
+      // The raced user-phase fires belong to THIS turn but aren't in the committed messages yet (their
+      // markers ride out on this hook's return), so fold them in before counting — otherwise a trigger
+      // that fired on the user surface would look untouched to its own per-turn cap.
+      const hist = fireHistory(ctx.session.messages);
+      for (const s of userOut.sources) {
+        hist.thisTurn.set(s.id, (hist.thisTurn.get(s.id) ?? 0) + 1);
+        hist.since.set(s.id, 0);
+      }
+      const cooled = applyCooldown(fired, hist);
+      markers.push(...cooled.markers);
+      for (const { trigger, kinds, matched } of cooled.kept) {
         if (kinds.includes('retract') && heldOff.has(trigger.id)) {
           suppressed.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'retract') });
           continue;

package/src/tools.ts

@@ -1,6 +1,6 @@
 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';
+import type { TriggerCondition, TriggerCooldown, TriggerKind, Trigger } from './types.js';
 
 declare module '@matatbread/matbot-plugin-api' {
   interface ToolContracts {
@@ -10,8 +10,8 @@ declare module '@matatbread/matbot-plugin-api' {
       | 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<{ id: string },          { action: 'add'; conditions: TriggerCondition[]; tool: string; params?: object; enabled?: boolean; cooldown?: TriggerCooldown }>
+      | ToolContract<Trigger,                 { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean; cooldown?: TriggerCooldown }>
       | ToolContract<Trigger,                 { action: 'disable'; id: string }>
       | ToolContract<Trigger,                 { action: 'enable'; id: string }>
       | ToolContract<{ id: string },          { action: 'remove'; id: string }>
@@ -53,14 +53,22 @@ const GUIDANCE =
   'invoke naming a tool that is not present fails soft — the trigger simply does nothing until it ' +
   'is. To fire a skill on a condition, invoke `skill_action` with `{ action: "use", name }` — `use` ' +
   'applies the skill as a directive (the firing case). (`{ action: "load" }` returns raw content for ' +
-  'reading/editing, not for firing — a `load` result is bare text the model may misread as the user speaking.)';
+  'reading/editing, not for firing — a `load` result is bare text the model may misread as the user speaking.)\n\n' +
+  'An optional `cooldown` rate-limits firing independently of matching — `{ maxPerTurn, quietTurns }`. ' +
+  'A turn is one genuine user message and everything that follows it (a retract redo or a follow-up ' +
+  'robo turn belongs to the turn that caused it). `maxPerTurn` caps fires within a turn across both ' +
+  'surfaces; `quietTurns` holds the trigger off for that many LATER turns after a fire (1 ⇒ never on ' +
+  'consecutive turns). Absent ⇒ unlimited, which is right for most triggers: a trigger that captures ' +
+  'what the user just said SHOULD fire every turn, and rate-limiting it silently loses data. Use a ' +
+  'cool-down for triggers whose consequence is a self-directed steer (critique, verify, reconsider), ' +
+  'where matching every turn is correct but acting every turn is a spin.';
 
 type TriggerActionInput =
   | { action: 'list' }
   | { action: 'query';  tool?: string; params?: unknown }
   | { 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: 'add';    conditions: TriggerCondition[]; tool: string; params?: unknown; enabled?: boolean; cooldown?: unknown }
+  | { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: unknown; enabled?: boolean; cooldown?: unknown }
   | { action: 'disable'; id: string }
   | { action: 'enable';  id: string }
   | { action: 'remove'; id: string }
@@ -75,6 +83,23 @@ function queryFilter(a: { tool?: unknown; params?: unknown }): { tool?: string;
   };
 }
 
+// A cool-down is valid if every field it carries is a whole number at or above its own minimum, which
+// differ by polarity: `maxPerTurn` counts PERMITTED fires, so 0 would mean "never fires" — an alias
+// for `disable` reached through a rate limit, silently and without the suspend flag a reader would
+// look for — while `quietTurns` counts BLOCKED turns, where 0 is an honest "no delay". `null` clears
+// the whole thing (the only way back to unlimited through a patch, since an omitted field means
+// "leave unchanged").
+function validCooldown(x: unknown): x is TriggerCooldown {
+  if (x === null || typeof x !== 'object') return false;
+  const c = x as { maxPerTurn?: unknown; quietTurns?: unknown };
+  const ok = (v: unknown, min: number): boolean => v === undefined || (typeof v === 'number' && Number.isInteger(v) && v >= min);
+  return ok(c.maxPerTurn, 1) && ok(c.quietTurns, 0);
+}
+const COOLDOWN_ERR =
+  '"cooldown" must be { maxPerTurn?: integer >= 1, quietTurns?: integer >= 0 }. ' +
+  'maxPerTurn 0 is rejected: a trigger that may never fire is a suspended trigger — use the ' +
+  '"disable" action, which keeps the conditions and is visible as such.';
+
 // A condition is valid if it has a recognised `kind` and a string `rule`.
 function validConditions(x: unknown): x is TriggerCondition[] {
   return Array.isArray(x) && x.every(c =>
@@ -114,10 +139,12 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           if (!validConditions(a.conditions)) { yield { type: 'error', message: `action "add" requires "conditions": [{ kind: ${KINDS.join('|')}, rule: string }].` }; return; }
           if (a.conditions.length === 0)      { yield { type: 'error', message: 'action "add" requires at least one condition.' }; return; }
           if (typeof a.tool !== 'string')     { yield { type: 'error', message: 'action "add" requires a string "tool" to invoke.' }; return; }
+          if (a.cooldown !== undefined && !validCooldown(a.cooldown)) { yield { type: 'error', message: COOLDOWN_ERR }; return; }
           const t = await manager.add({
             conditions: a.conditions,
             invoke:     { tool: a.tool, ...(a.params !== undefined ? { params: a.params } : {}) },
-            ...(a.enabled !== undefined ? { enabled: a.enabled } : {}),
+            ...(a.enabled  !== undefined ? { enabled:  a.enabled            } : {}),
+            ...(a.cooldown !== undefined ? { cooldown: a.cooldown as TriggerCooldown } : {}),
           });
           yield { type: 'result', value: { id: t.id } };
           return;
@@ -128,6 +155,7 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           if (!a.id) { yield { type: 'error', message: 'action "update" requires "id".' }; return; }
           if (a.conditions !== undefined && !validConditions(a.conditions)) { yield { type: 'error', message: '"conditions" must be [{ kind, rule }].' }; return; }
           if (a.tool !== undefined && typeof a.tool !== 'string')           { yield { type: 'error', message: '"tool" must be a string.' }; return; }
+          if (a.cooldown !== undefined && a.cooldown !== null && !validCooldown(a.cooldown)) { yield { type: 'error', message: COOLDOWN_ERR + ' Pass null to remove every limit.' }; return; }
           const priorTool = (a.tool !== undefined || a.params !== undefined)
             ? (await manager.get(a.id))?.invoke.tool ?? ''
             : '';
@@ -137,6 +165,8 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
               ? { invoke: { tool: a.tool ?? priorTool, ...(a.params !== undefined ? { params: a.params } : {}) } }
               : {}),
             ...(a.enabled !== undefined ? { enabled: a.enabled } : {}),
+            // null clears every limit; an omitted `cooldown` leaves the stored one untouched.
+            ...(a.cooldown !== undefined ? { cooldown: (a.cooldown === null ? {} : a.cooldown) as TriggerCooldown } : {}),
           });
           if (t === undefined) { yield { type: 'error', message: `Trigger not found: "${a.id}"` }; return; }
           yield { type: 'result', value: t };
@@ -189,7 +219,8 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
             triggers.push(await manager.add({
               conditions: t.conditions,
               invoke,
-              ...(t.enabled !== undefined ? { enabled: t.enabled } : {}),
+              ...(t.enabled  !== undefined ? { enabled:  t.enabled  } : {}),
+              ...(t.cooldown !== undefined ? { cooldown: t.cooldown } : {}),
             }));
           }
           yield { type: 'result', value: { triggers } };
@@ -231,6 +262,8 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
         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: 'On add/update, set false to keep but suspend the trigger (absent ⇒ enabled). To toggle an existing trigger, prefer the dedicated "disable"/"enable" actions.' },
+        cooldown:   { type: ['object', 'null'], description: 'On add/update, rate-limit firing: { maxPerTurn, quietTurns }. Omit to leave unchanged (absent ⇒ unlimited); null on update removes every limit.',
+          properties: { maxPerTurn: { type: 'integer', minimum: 1, description: 'Most fires allowed within one turn (>= 1; to stop a trigger firing at all, use "disable").' }, quietTurns: { type: 'integer', minimum: 0, description: 'Later turns held off after a fire; 1 ⇒ never on consecutive turns, 0 ⇒ no delay.' } } },
       },
     },
     executor,

package/src/types.ts

@@ -68,11 +68,38 @@ export interface TriggerInvoke {
   params?: unknown;
 }
 
+/**
+ * An optional rate limit on ONE trigger, independent of whether its conditions match. Conditions say
+ * *when* a trigger is relevant; a cool-down says *how often* it may act on that — the two are
+ * separate because a rule can be genuinely, correctly matched turn after turn (a critic rule matches
+ * every uncertain answer) while acting on it every time is a self-critique spin, not a service.
+ *
+ * Both limits are counted from the durable fire markers already in the session (see the marker
+ * helpers in plugin.ts), so a cool-down survives restarts, session reload and a moved backend without
+ * any in-memory state. A *turn* here is a genuine (non-robo) user message and everything that follows
+ * it — a retract redo or a followup robo turn belongs to the turn that caused it, not a new one.
+ *
+ * Absent ⇒ no limit, which stays the default: most triggers (e.g. capturing a stated fact) SHOULD
+ * fire on consecutive turns, and rate-limiting them would silently lose data.
+ */
+export interface TriggerCooldown {
+  /** Most fires allowed within one turn, counting both surfaces. At least 1: the two fields have
+   *  opposite polarity — this one counts PERMITTED fires, so 0 would mean "never fires", which is
+   *  `enabled: false` reached silently through a rate limit and is rejected. Absent ⇒ unlimited. */
+  maxPerTurn?: number;
+  /** Genuine user turns the trigger stays held off for after a fire. 1 ⇒ never on consecutive turns
+   *  (a fire on turn N is held off on N+1, allowed again on N+2). This one counts BLOCKED turns, so
+   *  0 is an honest "no delay" and means the same as absent. */
+  quietTurns?: number;
+}
+
 export interface Trigger {
   id:         string;
   version:    string;
   conditions: TriggerCondition[];
   invoke:     TriggerInvoke;
+  /** Rate limit on firing, independent of matching. Absent ⇒ unlimited — see {@link TriggerCooldown}. */
+  cooldown?:  TriggerCooldown;
   /** Absent ⇒ enabled. A disabled trigger is kept but never evaluated. */
   enabled?:   boolean;
   createdAt:  string;
@@ -84,6 +111,7 @@ export interface TriggerSpec {
   conditions: TriggerCondition[];
   invoke:     TriggerInvoke;
   enabled?:   boolean;
+  cooldown?:  TriggerCooldown;
 }
 
 /**