@matatbread/matbot-triggers 0.4.12 → 0.4.16

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.12",
+  "version": "0.4.16",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -33,11 +33,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.12"
+    "@matatbread/matbot-plugin-api": "^0.4.16"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "@matatbread/matbot-plugin-api": "^0.4.12"
+    "@matatbread/matbot-plugin-api": "^0.4.16"
   },
   "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,26 +1,27 @@
 import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
 import type { TriggerManager } from './manager.js';
-import type { TriggerCondition, TriggerCooldown, TriggerKind, Trigger } from './types.js';
+import { checkInvocation } from './dispatch.js';
+import type { TriggerCondition, TriggerCooldown, TriggerKind, Trigger, ReportedTrigger } from './types.js';
 
 declare module '@matatbread/matbot-plugin-api' {
   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 ToolContract / the multi-action note on ToolContracts).
     trigger_action:
-      | ToolContract<{ triggers: Trigger[] }, { action: 'list' }>
-      | ToolContract<{ triggers: Trigger[] }, { action: 'query'; tool?: string; params?: object }>
-      | ToolContract<Trigger,                 { action: 'get'; id: string }>
+      | ToolContract<{ triggers: ReportedTrigger[] }, { action: 'list' }>
+      | ToolContract<{ triggers: ReportedTrigger[] }, { action: 'query'; tool?: string; params?: object }>
+      | ToolContract<ReportedTrigger,                 { action: 'get'; id: string }>
       | ToolContract<{ id: string },          { action: 'add'; 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 }>
-      | 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 }>;
+      | ToolContract<ReportedTrigger,                 { action: 'update'; id: string; conditions?: TriggerCondition[]; tool?: string; params?: object; enabled?: boolean; cooldown?: TriggerCooldown | null }>
+      | ToolContract<ReportedTrigger,                 { action: 'disable'; id: string }>
+      | ToolContract<ReportedTrigger,                 { action: 'enable'; id: string }>
+      | ToolContract<{ id: string },                  { action: 'remove'; id: string }>
+      | ToolContract<{ triggers: ReportedTrigger[] }, { action: 'move'; tool?: string; params?: object; toTool: string; toParams?: object }>
+      | ToolContract<{ triggers: ReportedTrigger[] }, { action: 'copy'; tool?: string; params?: object; toTool: string; toParams?: object }>;
     triggers_config:
       | ToolContract<{ classifierProvider: string | null; available: string[] }, { action: 'get' }>
       | ToolContract<{ classifierProvider: string },                             { action: 'set'; provider: string }>
@@ -52,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` ' +
@@ -80,6 +84,11 @@ type TriggerActionInput =
   | { action: 'move';   tool?: string; params?: unknown; toTool: string; toParams?: unknown }
   | { action: 'copy';   tool?: string; params?: unknown; toTool: string; toParams?: unknown };
 
+// `enabled` resolved for reporting (see ReportedTrigger): it is stored only when explicitly written, so
+// a listing otherwise carried it for some triggers and not others, leaving a reader to know "absent ⇒
+// enabled" rather than see it. Applied at the yield sites only — the stored document is untouched.
+const reported = (t: Trigger): ReportedTrigger => ({ ...t, enabled: t.enabled !== false });
+
 // The query selector shared by query/move/copy: `tool`/`params` narrow the set by what a trigger invokes.
 function queryFilter(a: { tool?: unknown; params?: unknown }): { tool?: string; params?: unknown } {
   return {
@@ -113,20 +122,20 @@ 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 };
 
       switch (args.action) {
         case 'list': {
-          yield { type: 'result', value: { triggers: await manager.all() } };
+          yield { type: 'result', value: { triggers: (await manager.all()).map(reported) } };
           return;
         }
 
         case 'query': {
           const a = args as Extract<TriggerActionInput, { action: 'query' }>;
-          yield { type: 'result', value: { triggers: await manager.query(queryFilter(a)) } };
+          yield { type: 'result', value: { triggers: (await manager.query(queryFilter(a))).map(reported) } };
           return;
         }
 
@@ -135,7 +144,7 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           if (!id) { yield { type: 'error', message: 'action "get" requires "id".' }; return; }
           const t = await manager.get(id);
           if (!t) { yield { type: 'error', message: `Trigger not found: "${id}"` }; return; }
-          yield { type: 'result', value: t };
+          yield { type: 'result', value: reported(t) };
           return;
         }
 
@@ -145,9 +154,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 } : {}),
           });
@@ -161,20 +173,22 @@ 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 } : {}),
           });
           if (t === undefined) { yield { type: 'error', message: `Trigger not found: "${a.id}"` }; return; }
-          yield { type: 'result', value: t };
+          yield { type: 'result', value: reported(t) };
           return;
         }
 
@@ -187,7 +201,7 @@ export function createTriggerActionTool(manager: TriggerManager): Tool<ToolResul
           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 };
+          yield { type: 'result', value: reported(t) };
           return;
         }
 
@@ -205,10 +219,12 @@ 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 triggers: Trigger[] = [];
+          const refused = await checkInvocation(services, invoke);
+          if (refused !== undefined) { yield { type: 'error', message: `No triggers moved — ${refused}.` }; return; }
+          const triggers: ReportedTrigger[] = [];
           for (const t of await manager.query(queryFilter(a))) {
             const updated = await manager.update(t.id, { invoke });
-            if (updated !== undefined) triggers.push(updated);
+            if (updated !== undefined) triggers.push(reported(updated));
           }
           yield { type: 'result', value: { triggers } };
           return;
@@ -219,14 +235,16 @@ 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 triggers: Trigger[] = [];
+          const refused = await checkInvocation(services, invoke);
+          if (refused !== undefined) { yield { type: 'error', message: `No triggers copied — ${refused}.` }; return; }
+          const triggers: ReportedTrigger[] = [];
           for (const t of await manager.query(queryFilter(a))) {
-            triggers.push(await manager.add({
+            triggers.push(reported(await manager.add({
               conditions: t.conditions,
               invoke,
               ...(t.enabled  !== undefined ? { enabled:  t.enabled  } : {}),
               ...(t.cooldown !== undefined ? { cooldown: t.cooldown } : {}),
-            }));
+            })));
           }
           yield { type: 'result', value: { triggers } };
           return;

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;
@@ -106,6 +107,16 @@ export interface Trigger {
   updatedAt:  string;
 }
 
+/**
+ * A trigger as `trigger_action` REPORTS it: `enabled` resolved rather than omitted.
+ *
+ * Stored documents carry `enabled` only when it was explicitly written, so a listing showed it for some
+ * triggers and not others — and "absent ⇒ enabled" is a rule a reader has to know rather than see. The
+ * resolution happens at the tool boundary only: stored shape and {@link Triggers} consumers are
+ * untouched, so no write can persist a value nobody asked for.
+ */
+export type ReportedTrigger = Omit<Trigger, 'enabled'> & { enabled: boolean };
+
 /** Fields a caller supplies when creating or replacing a trigger; identity/versioning is the store's. */
 export interface TriggerSpec {
   conditions: TriggerCondition[];