@matatbread/matbot-triggers 0.4.7 → 0.4.14

package/package.json

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

package/src/dispatch.ts

@@ -1,6 +1,6 @@
 import type { MatbotMachine, Session, PromptFn, MessageContent } from '@matatbread/matbot-plugin-api';
 import { invokeTool } from '@matatbread/matbot-plugin-api';
-import type { Trigger } from './types.js';
+import type { Trigger, TriggerInvoke } from './types.js';
 
 export interface DispatchOutcome {
   /** Whether the tool yielded a result — i.e. whether the model should be woken with it (inject). */
@@ -12,6 +12,42 @@ export interface DispatchOutcome {
   markers:   MessageContent[];
 }
 
+/** core's `TOOL_INPUT_INVALID`, the `code` on the error event a validator's rejection yields. Spelled
+ *  here rather than imported because triggers depends on plugin-api alone; it is the one error a stored
+ *  trigger can only recover from by being edited, which is why it is reported to the model. */
+export const TOOL_INPUT_INVALID = 422;
+
+/**
+ * The input a trigger's tool is actually called with. An omitted `params` is `{}`, never `undefined`:
+ * every tool input is an object (the model's own call of a parameterless tool sends `{}`), so passing
+ * `undefined` made every such trigger fail validation — `remember_fact` and a `tool_function` with no
+ * arguments among them — while reading as "no params needed" to whoever wrote it.
+ */
+export function invocationParams(invoke: TriggerInvoke): unknown {
+  return invoke.params ?? {};
+}
+
+// core declares `ToolCallValidator` on MatbotServices, and triggers does not depend on core, so the key
+// is read structurally. Same shape as core's `ToolInputValidator`.
+interface InvocationValidator {
+  validateToolCall(tool: string, parameters: unknown): Promise<{ path: string; message: string }[] | undefined>;
+}
+
+/**
+ * Check an invocation against the tool's declared input BEFORE it is stored, with the same validator the
+ * executor applies when the trigger fires — so a trigger that could never run is refused while its author
+ * is present to fix it, rather than failing silently on some later turn. Returns the rejection as text,
+ * or `undefined` to accept. A tool that is not registered, or no validator, is accepted: a trigger
+ * naming an absent tool fails soft by design, and nothing here can check what nothing declares.
+ */
+export async function checkInvocation(services: MatbotMachine, invoke: TriggerInvoke): Promise<string | undefined> {
+  if (services.tools.resolve(invoke.tool) === null) return undefined;
+  const validator = (services as MatbotMachine & { ToolCallValidator?: InvocationValidator }).ToolCallValidator;
+  const errs = await validator?.validateToolCall(invoke.tool, invocationParams(invoke));
+  if (errs === undefined || errs.length === 0) return undefined;
+  return `params do not match tool "${invoke.tool}": ${errs.map(e => `${e.path}: ${e.message}`).join('; ')}`;
+}
+
 /**
  * Invoke a fired trigger's tool, observing its output. The observational rule decides whether the
  * model wakes: a tool that yields a `result` is producing model-facing content (`hadResult` → the
@@ -31,10 +67,11 @@ export async function dispatchTrigger(
   // The runner reframes this for the tools it runs itself (INTERRUPTED_TOOL_RESULT); a trigger's tool runs
   // outside that loop, so the same reframing has to happen here. The trace is still recorded — a trigger
   // that was interrupted did nothing, and a post-mortem wants to know that — just not as an error.
-  const fail = (error: string): void => {
+  // `code` rides along so the next turn can tell a malformed invocation from an ordinary tool failure.
+  const fail = (error: string, code?: number): void => {
     const data = ctx.signal.aborted
       ? { triggerId: trigger.id, tool: trigger.invoke.tool, interrupted: true }
-      : { triggerId: trigger.id, tool: trigger.invoke.tool, error };
+      : { triggerId: trigger.id, tool: trigger.invoke.tool, error, ...(code !== undefined ? { code } : {}) };
     markers.push({ type: 'marker', creator: 'triggers', data });
   };
 
@@ -54,7 +91,7 @@ export async function dispatchTrigger(
     // The prompt (when the firing hook carries one — a live interactive session behind this turn) is
     // forwarded so a trigger can invoke an interactive tool (e.g. `ask_user`) for real; absent, the
     // tool runs non-interactively and a prompt attempt surfaces as a normal tool error.
-    const events = invokeTool(services, trigger.invoke.tool, trigger.invoke.params, {
+    const events = invokeTool(services, trigger.invoke.tool, invocationParams(trigger.invoke), {
       session:  ctx.session,
       signal:   ctx.signal,
       provider: ctx.provider,
@@ -66,7 +103,7 @@ export async function dispatchTrigger(
       else if (ev.type === 'marker') { markers.push({ type: 'marker', creator: ev.creator, data: ev.data }); }
       else if (ev.type === 'error')  {
         if (!ctx.signal.aborted) console.warn(`[triggers] trigger ${trigger.id} tool "${trigger.invoke.tool}" errored: ${ev.message}`);
-        fail(ev.message);
+        fail(ev.message, ev.code);
       }
     }
   } catch (e) {

package/src/plugin.ts

@@ -1,7 +1,7 @@
 import { PLUGIN_API_VERSION } from '@matatbread/matbot-plugin-api';
 import type { MatbotPluginSpec, MatbotMachine, Store, Message, MessageContent, Session, PromptFn, DeferredCorrection } from '@matatbread/matbot-plugin-api';
 import { TriggerManager } from './manager.js';
-import { dispatchTrigger, renderResult } from './dispatch.js';
+import { dispatchTrigger, renderResult, TOOL_INPUT_INVALID } from './dispatch.js';
 import { createTriggerActionTool, createTriggersConfigTool } from './tools.js';
 import type { Trigger, Triggers, FiredCondition, TriggerCooldown } from './types.js';
 
@@ -102,6 +102,36 @@ function hasCorrection(c: DeferredCorrection): boolean {
   return (c.ephemeral?.length ?? 0) > 0 || (c.durable?.length ?? 0) > 0;
 }
 
+/**
+ * The fired triggers whose call the tool REJECTED as malformed, rendered for the model. Such a trigger
+ * is rejected every time it fires — its stored invocation is wrong, not the turn — and the only trace
+ * was an LLM-invisible marker and a server-log warning, so nobody learned of it until someone went
+ * looking. Reported on the next genuine user turn (`from` is that user message's index), where the model
+ * can say so and repair it with `trigger_action update`. The window is the markers since the PREVIOUS
+ * genuine user message, robo resubmits included, so each firing is reported exactly once.
+ */
+export function invalidInvocationReport(messages: readonly Message[], from: number): MessageContent[] | undefined {
+  const lines: string[] = [];
+  for (let i = from - 1; i >= 0; i--) {
+    const m = messages[i]!;
+    if (m.role === 'user' && !m.content.every(c => c.origin === 'robo')) break;
+    for (const c of m.content) {
+      if (c.type !== 'marker' || c.creator !== 'triggers') continue;
+      const d = c.data as { triggerId?: unknown; tool?: unknown; error?: unknown; code?: unknown };
+      if (d.code !== TOOL_INPUT_INVALID || typeof d.triggerId !== 'string') continue;
+      lines.unshift(`- trigger ${d.triggerId} (invokes "${String(d.tool)}"): ${String(d.error)}`);
+    }
+  }
+  if (lines.length === 0) return undefined;
+  return [{ type: 'text', text: fence(
+    'On the previous turn, these triggers fired but their tool rejected the call, so they did nothing. ' +
+    'The stored `invoke.params` do not match what the tool accepts, and will fail the same way every time ' +
+    'the trigger fires:\n' + lines.join('\n') + '\n\n' +
+    'Tell the user. If the correct params are clear from the error and the tool\'s parameters, fix the ' +
+    'trigger with `trigger_action` (action "update", with its id and the corrected "params").',
+  ) }];
+}
+
 // The core retraction marker's creator (core/src/session-runner.ts). Hardcoded as a
 // documented cross-package string contract — markers are keyed by a creator string, and triggers
 // depends only on plugin-api, not core. Keep in sync with RETRACTION_CREATOR there.
@@ -295,7 +325,7 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
   // swap-following proxy) on every call, so it always reflects the live backend and current partition.
   await services.register('Triggers', manager);
 
-  services.tools.register(createTriggerActionTool(manager));
+  services.tools.register(createTriggerActionTool(manager, services));
   services.tools.register(createTriggersConfigTool(services));
 
   // In-flight user-phase evaluations, keyed by the turn's traceId. The `screen` hook kicks one off
@@ -375,8 +405,15 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
       // No traceId ⇒ can't correlate to the followup hook that consumes the verdict; skip racing (a
       // direct runSession caller without a traceId simply gets no user-phase triggers). In the pump —
       // the only real entry point — traceId is always set.
+      // Rejections from the previous turn ride out ephemerally on whichever return this hook takes.
+      const report = invalidInvocationReport(ctx.session.messages, ctx.session.messages.lastIndexOf(lastUser));
+      const withReport = (eph?: MessageContent[]): { ephemeral?: MessageContent[] } => {
+        const all = [...(report ?? []), ...(eph ?? [])];
+        return all.length > 0 ? { ephemeral: all } : {};
+      };
+
       const traceId = ctx.config.traceId;
-      if (traceId === undefined) return;
+      if (traceId === undefined) return report ? withReport() : undefined;
 
       // Kick off classify+dispatch; do not await. The record's `ready`/`fenced` let the runner poll
       // synchronously; `.catch` neutralises an aborted-turn rejection (the classifier shares the turn's
@@ -397,7 +434,7 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
         if (rec.ready && hasCorrection(rec.correction) && !rec.claimed) {
           rec.claimed = true;
           return {
-            ...(rec.correction.ephemeral ? { ephemeral: rec.correction.ephemeral } : {}),
+            ...withReport(rec.correction.ephemeral),
             ...(rec.correction.durable   ? { durable:   rec.correction.durable   } : {}),
           };
         }
@@ -406,6 +443,7 @@ export async function setupTriggers(services: MatbotMachine): Promise<TriggerMan
       // Race path: hand the runner a deferred that claims the correction exactly once for an in-situ
       // restart (or a pre-generation fold). Not settled / no result / already claimed ⇒ undefined.
       return {
+        ...withReport(),
         deferred: {
           claim: (): DeferredCorrection | undefined => {
             if (!rec.ready || rec.claimed || !hasCorrection(rec.correction)) return undefined;

package/src/tools.ts

@@ -1,5 +1,6 @@
 import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
 import type { TriggerManager } from './manager.js';
+import { checkInvocation } from './dispatch.js';
 import type { TriggerCondition, TriggerCooldown, TriggerKind, Trigger } from './types.js';
 
 declare module '@matatbread/matbot-plugin-api' {
@@ -11,7 +12,11 @@ declare module '@matatbread/matbot-plugin-api' {
       | 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; cooldown?: TriggerCooldown }>
-      | ToolContract<Trigger,                 { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean; cooldown?: TriggerCooldown }>
+      // `cooldown: null` CLEARS every limit, which an omitted `cooldown` deliberately does not (it
+      // leaves the stored one untouched). The executor has always accepted it and the web UI has always
+      // sent it; only this arm omitted it, so a documented call was untypeable — invisible until the
+      // params type was actually enforced. `add` takes no `null`: there is no prior limit to clear.
+      | ToolContract<Trigger,                 { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean; cooldown?: TriggerCooldown | null }>
       | ToolContract<Trigger,                 { action: 'disable'; id: string }>
       | ToolContract<Trigger,                 { action: 'enable'; id: string }>
       | ToolContract<{ id: string },          { action: 'remove'; id: string }>
@@ -48,7 +53,10 @@ const GUIDANCE =
   'verification, so keep it and add a follow-up turn carrying the output (e.g. critique/verify the ' +
   'existing answer — it must remain in context). Choose retract vs followup by whether a match means ' +
   '"this is wrong" vs "look at this again".\n\n' +
-  '`invoke` names a tool and its params, run verbatim when the trigger fires. If the tool produces ' +
+  '`invoke` names a tool and its params (omitted ⇒ `{}`), run verbatim when the trigger fires. The ' +
+  'params are checked against the tool\'s declared parameters when the trigger is saved, so match them ' +
+  'exactly; a trigger whose call is rejected when it fires is reported on the next turn — fix it with ' +
+  '"update". If the tool produces ' +
   'a result, the model is woken with it; a pure side-effect tool (no result) runs silently. An ' +
   '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` ' +
@@ -61,7 +69,8 @@ const GUIDANCE =
   '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.';
+  'where matching every turn is correct but acting every turn is a spin. On "update", omitting ' +
+  '`cooldown` leaves the stored limits untouched; pass `null` to clear them.';
 
 type TriggerActionInput =
   | { action: 'list' }
@@ -108,7 +117,7 @@ function validConditions(x: unknown): x is TriggerCondition[] {
     typeof (c as { rule?: unknown }).rule === 'string');
 }
 
-export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResultOf<'trigger_action'>> {
+export function createTriggerActionTool(manager: TriggerManager, services: MatbotMachine): Tool<ToolResultOf<'trigger_action'>> {
   const executor: ToolExecutor<ToolResultOf<'trigger_action'>> = {
     async *execute(input: unknown, _ctx: ToolContext) {
       const args = input as Partial<TriggerActionInput> & { action?: string };
@@ -140,9 +149,12 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           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 invoke  = { tool: a.tool, ...(a.params !== undefined ? { params: a.params } : {}) };
+          const refused = await checkInvocation(services, invoke);
+          if (refused !== undefined) { yield { type: 'error', message: `Trigger not added — ${refused}.` }; return; }
           const t = await manager.add({
             conditions: a.conditions,
-            invoke:     { tool: a.tool, ...(a.params !== undefined ? { params: a.params } : {}) },
+            invoke,
             ...(a.enabled  !== undefined ? { enabled:  a.enabled            } : {}),
             ...(a.cooldown !== undefined ? { cooldown: a.cooldown as TriggerCooldown } : {}),
           });
@@ -156,14 +168,16 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           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 ?? ''
-            : '';
+          const invoke = a.tool !== undefined || a.params !== undefined
+            ? { tool: a.tool ?? (await manager.get(a.id))?.invoke.tool ?? '', ...(a.params !== undefined ? { params: a.params } : {}) }
+            : undefined;
+          // Only an edit to the invocation is checked, so a broken trigger can still be disabled or have
+          // its conditions changed without first being repaired.
+          const refused = invoke !== undefined ? await checkInvocation(services, invoke) : undefined;
+          if (refused !== undefined) { yield { type: 'error', message: `Trigger not updated — ${refused}.` }; return; }
           const t = await manager.update(a.id, {
             ...(a.conditions !== undefined ? { conditions: a.conditions } : {}),
-            ...(a.tool !== undefined || a.params !== undefined
-              ? { invoke: { tool: a.tool ?? priorTool, ...(a.params !== undefined ? { params: a.params } : {}) } }
-              : {}),
+            ...(invoke !== undefined ? { invoke } : {}),
             ...(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 } : {}),
@@ -200,6 +214,8 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           if (typeof a.toTool !== 'string')                  { yield { type: 'error', message: 'action "move" requires a string "toTool" to re-target the selected triggers onto.' }; return; }
           if (a.tool === undefined && a.params === undefined) { yield { type: 'error', message: 'action "move" requires a filter ("tool" and/or "params") selecting which triggers to re-target — refusing to move every trigger.' }; return; }
           const invoke = { tool: a.toTool, ...(a.toParams !== undefined ? { params: a.toParams } : {}) };
+          const refused = await checkInvocation(services, invoke);
+          if (refused !== undefined) { yield { type: 'error', message: `No triggers moved — ${refused}.` }; return; }
           const triggers: Trigger[] = [];
           for (const t of await manager.query(queryFilter(a))) {
             const updated = await manager.update(t.id, { invoke });
@@ -214,6 +230,8 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           if (typeof a.toTool !== 'string')                  { yield { type: 'error', message: 'action "copy" requires a string "toTool" to point the duplicates at.' }; return; }
           if (a.tool === undefined && a.params === undefined) { yield { type: 'error', message: 'action "copy" requires a filter ("tool" and/or "params") selecting which triggers to duplicate — refusing to duplicate every trigger.' }; return; }
           const invoke = { tool: a.toTool, ...(a.toParams !== undefined ? { params: a.toParams } : {}) };
+          const refused = await checkInvocation(services, invoke);
+          if (refused !== undefined) { yield { type: 'error', message: `No triggers copied — ${refused}.` }; return; }
           const triggers: Trigger[] = [];
           for (const t of await manager.query(queryFilter(a))) {
             triggers.push(await manager.add({

package/src/types.ts

@@ -62,7 +62,8 @@ export interface FiredCondition {
   why?:  string;
 }
 
-/** The tool call a matched trigger makes. `params` is passed verbatim as the tool's input. */
+/** The tool call a matched trigger makes. `params` is passed verbatim as the tool's input; absent, the
+ *  tool is called with `{}`, as the model calls a tool that takes no parameters. */
 export interface TriggerInvoke {
   tool:    string;
   params?: unknown;