@matatbread/matbot-triggers 0.1.6

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mat Woolf
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,5 @@
+# @matatbread/matbot-triggers
+
+This is a [matbot](https://github.com/MatAtBread/matbot) plugin.
+
+Data-driven hooks: stored conditions that, when an LLM classifier judges them matched, invoke a tool. Cross-runtime (node + browser).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@matatbread/matbot-triggers",
+  "matbotRuntime": [
+    "node",
+    "browser"
+  ],
+  "version": "0.1.6",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "description": "Data-driven hooks: stored conditions that, when an LLM classifier judges them matched, invoke a tool. Cross-runtime (node + browser).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MatAtBread/matbot.git",
+    "directory": "plugins/triggers"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@matatbread/matbot-plugin-api": "0.1.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@matatbread/matbot-plugin-api": "0.1.6"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/dispatch.ts

@@ -0,0 +1,100 @@
+import type { MatbotMachine, Session, ToolContext, PromptFn, FormField, MessageContent } from '@matatbread/matbot-plugin-api';
+import type { Trigger } from './types.js';
+
+// Fallback when the firing hook carries no interactive prompt (cron/background run, or a frontend
+// that supplied none): a tool that tries to prompt resolves to a rejection it surfaces as a normal
+// tool error. When the hook DOES carry a prompt (a live interactive session behind this turn), it is
+// forwarded instead, so a trigger can invoke an interactive tool (e.g. `ask_user`) for real.
+const rejectingPrompt: PromptFn = (((p: string | FormField): Promise<string> => {
+  const label = typeof p === 'string' ? p : p.label;
+  return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
+}) as PromptFn);
+
+export interface DispatchOutcome {
+  /** Whether the tool yielded a result — i.e. whether the model should be woken with it (inject). */
+  hadResult: boolean;
+  /** The yielded result (meaningful only when `hadResult`). */
+  result:    unknown;
+  /** Durable markers to persist: any the tool emitted, plus a synthesised error marker if it failed.
+   *  These outlive the silent firing, so a post-mortem can see what each trigger actually did. */
+  markers:   MessageContent[];
+}
+
+/**
+ * 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
+ * caller injects it); a tool that yields none is a silent side-effect (the model never wakes). Any
+ * `marker` events the tool emits are collected for the caller to persist, and a tool that errors or
+ * throws — or names an absent tool — is recorded as an error marker rather than vanishing into a log.
+ */
+export async function dispatchTrigger(
+  services: MatbotMachine,
+  trigger:  Trigger,
+  ctx:      { session: Session; signal: AbortSignal; provider: string; prompt?: PromptFn },
+): Promise<DispatchOutcome> {
+  const markers: MessageContent[] = [];
+  const fail = (error: string): void => {
+    markers.push({ type: 'marker', creator: 'triggers', data: { triggerId: trigger.id, tool: trigger.invoke.tool, error } });
+  };
+
+  let result: unknown;
+  let hadResult = false;
+  // Total by construction: every path through here either returns an outcome or records a `fail`
+  // marker — nothing escapes. A trigger's tool can throw, hang-then-abort, or emit an error event,
+  // and the worst case is "this trigger did nothing and left a trace"; sibling triggers, the hook,
+  // and the session are unaffected. (The hook dispatcher's own try/catch is a second layer behind this.)
+  try {
+    const tool = services.tools.resolve(trigger.invoke.tool);
+    if (tool === null) {
+      console.warn(`[triggers] trigger ${trigger.id} invokes unknown tool "${trigger.invoke.tool}"; skipped.`);
+      fail(`tool "${trigger.invoke.tool}" not registered`);
+      return { hadResult: false, result: undefined, markers };
+    }
+
+    const toolCtx: ToolContext = {
+      callId:       crypto.randomUUID(),
+      session:      ctx.session,
+      signal:       ctx.signal,
+      vault:        services.Vault,
+      provider:     ctx.provider,
+      prompt:       ctx.prompt ?? rejectingPrompt,
+      // Forward the prompt into plugin loading too (mirrors the normal loop): collision resolution
+      // during a loaded plugin's setup() prompts the user, so a trigger that loads a plugin (e.g. the
+      // DRTX case — an agent reply triggers `plugin(load …)`) is interactive end-to-end, not just at
+      // the tool's own ctx.prompt calls.
+      loadPlugin:   (specifier: string) => services.loadPlugin(specifier, ctx.prompt ?? rejectingPrompt),
+      unloadPlugin: (specifier: string) => services.unloadPlugin(specifier),
+      ...(services.workdir    !== undefined ? { workdir:    services.workdir    } : {}),
+      ...(services.configPath !== undefined ? { configPath: services.configPath } : {}),
+      ...(services.files      !== undefined ? { files:      services.files      } : {}),
+    };
+
+    for await (const ev of tool.executor.execute(trigger.invoke.params, toolCtx)) {
+      if      (ev.type === 'result') { result = ev.value; hadResult = true; }
+      else if (ev.type === 'marker') { markers.push({ type: 'marker', creator: ev.creator, data: ev.data }); }
+      else if (ev.type === 'error')  {
+        console.warn(`[triggers] trigger ${trigger.id} tool "${trigger.invoke.tool}" errored: ${ev.message}`);
+        fail(ev.message);
+      }
+    }
+  } catch (e) {
+    console.warn(`[triggers] trigger ${trigger.id} tool "${trigger.invoke.tool}" threw:`, e);
+    fail(e instanceof Error ? e.message : String(e));
+  }
+
+  return { hadResult, result, markers };
+}
+
+/**
+ * Render a tool result into the text injected for the model. A string is used verbatim; an object
+ * with a string `content` field (the shape `skill_action(load)` and other prose-producing tools
+ * return) uses that; anything else is shown as JSON. (Rendering fidelity for arbitrary tools is a
+ * known rough edge — see the slice notes.)
+ */
+export function renderResult(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value !== null && typeof value === 'object' && typeof (value as { content?: unknown }).content === 'string') {
+    return (value as { content: string }).content;
+  }
+  return JSON.stringify(value, null, 2);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type { Trigger, TriggerCondition, 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';
+export { createTriggerActionTool, createTriggersConfigTool } from './tools.js';
+export { createTriggersPlugin, setupTriggers, plugin } from './plugin.js';

package/src/manager.ts

@@ -0,0 +1,219 @@
+import type { Store, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type { Trigger, TriggerSpec, TriggerSurface, TriggerKind, Triggers, FiredCondition } from './types.js';
+import { surfaceOfKind } from './types.js';
+
+const MAX_MSG_CHARS = 1500;
+
+// Back-compat default: installs that configured a provider literally named "skills-classifier" (the
+// former hard-coded classifier name) keep working with no migration. A `classifierProvider` setting
+// overrides it; absent both, the classifier falls back to the turn's own provider.
+const LEGACY_CLASSIFIER = 'skills-classifier';
+
+function clip(text: string): string {
+  if (text.length <= MAX_MSG_CHARS) return text;
+  const half = Math.floor((MAX_MSG_CHARS - 3) / 2);
+  return text.slice(0, half) + '...' + text.slice(-half);
+}
+
+/** Stable identity for seed idempotency: a trigger is "the same" if it invokes the same tool with
+ *  the same params. Triggers carry no name, so the invocation is the natural key. */
+function invokeKey(t: { invoke: Trigger['invoke'] }): string {
+  return t.invoke.tool + '\u0000' + JSON.stringify(t.invoke.params ?? null);
+}
+
+/**
+ * Owns the live trigger set: an in-memory list backed by a {@link Store} for persistence. All CRUD
+ * goes through here so the plugin's hooks and the `trigger_action` tool share one source of truth.
+ * Constructed only with web-platform primitives, so it runs in the browser too.
+ */
+export class TriggerManager implements Triggers {
+  private readonly triggers = new Map<string, Trigger>();
+  private readonly store:    Store<Trigger>;
+  private readonly services: MatbotMachine;
+  // Aborts on teardown (clear()), ending the mounted-swap subscription set up in setupTriggers.
+  private readonly lifecycle = new AbortController();
+
+  constructor(store: Store<Trigger>, services: MatbotMachine) {
+    this.store    = store;
+    this.services = services;
+  }
+
+  /** Ends with the manager (teardown). Hand to `services.mounted.consume` so a StorageBackend swap
+   *  re-reads the new backend's triggers, and the loop stops when the plugin unloads. */
+  get signal(): AbortSignal { return this.lifecycle.signal; }
+
+  // The classifier provider, resolved live per evaluation (so a triggers_config change takes effect on
+  // the next turn): the `classifierProvider` setting if set and valid, else the legacy "skills-classifier"
+  // provider if present, else the current turn's own provider. There is always a turn provider to fall
+  // back to, so the classifier always has a model — triggers work with zero config.
+  async resolveClassifierProvider(turnProvider: string): Promise<string> {
+    const pinned = await this.services.settings().get<string>('classifierProvider');
+    if (pinned !== undefined && this.services.providers.has(pinned)) return pinned;
+    if (this.services.providers.has(LEGACY_CLASSIFIER)) return LEGACY_CLASSIFIER;
+    return turnProvider;
+  }
+
+  /** (Re)load persisted triggers into memory. Re-runnable: the initial boot load and every later
+   *  StorageBackend swap funnel through here. Reading `this.store` (a swap-following proxy) always hits
+   *  the live backend, so a swap re-reads the new backend's triggers. Clears first — the old in-memory
+   *  set belongs to the displaced backend. */
+  async load(): Promise<void> {
+    this.triggers.clear();
+    const { items } = await this.store.query({});
+    for (const t of items) {
+      this.triggers.set(t.id, t);
+    }
+  }
+
+  all(): Trigger[] { return [...this.triggers.values()]; }
+  get(id: string): Trigger | undefined { return this.triggers.get(id); }
+
+  /** Triggers whose invocation matches the filter: `tool` (if given) must equal `invoke.tool`, and
+   *  `params` (if given) must deep-equal `invoke.params`. The natural "which trigger(s) fire tool X
+   *  (with these args)" lookup — e.g. the one that loads a given skill. */
+  query(filter: { tool?: string; params?: unknown }): Trigger[] {
+    return this.all().filter(t => {
+      if (filter.tool !== undefined && t.invoke.tool !== filter.tool) return false;
+      if (filter.params !== undefined &&
+          JSON.stringify(t.invoke.params ?? null) !== JSON.stringify(filter.params)) return false;
+      return true;
+    });
+  }
+
+  async add(spec: TriggerSpec): Promise<Trigger> {
+    const now = new Date().toISOString();
+    const doc: Trigger = {
+      id:         crypto.randomUUID(),
+      version:    Date.now().toString(),
+      conditions: spec.conditions,
+      invoke:     spec.invoke,
+      ...(spec.enabled !== undefined ? { enabled: spec.enabled } : {}),
+      createdAt:  now,
+      updatedAt:  now,
+    };
+    await this.store.set(doc.id, doc);
+    this.triggers.set(doc.id, doc);
+    return doc;
+  }
+
+  async update(id: string, patch: Partial<TriggerSpec>): Promise<Trigger | undefined> {
+    const cur = this.triggers.get(id);
+    if (cur === undefined) return undefined;
+    return this.casMutate(cur, prev => ({
+      ...prev,
+      ...(patch.conditions !== undefined ? { conditions: patch.conditions } : {}),
+      ...(patch.invoke     !== undefined ? { invoke:     patch.invoke     } : {}),
+      ...(patch.enabled    !== undefined ? { enabled:    patch.enabled    } : {}),
+      version:   Date.now().toString(),
+      updatedAt: new Date().toISOString(),
+    }));
+  }
+
+  async remove(id: string): Promise<boolean> {
+    const cur = this.triggers.get(id);
+    if (cur === undefined) return false;
+    await this.store.delete(id, cur.version);
+    this.triggers.delete(id);
+    return true;
+  }
+
+  async importIfAbsent(spec: TriggerSpec): Promise<Trigger> {
+    const key      = invokeKey(spec);
+    const existing = this.all().find(t => invokeKey(t) === key);
+    if (existing !== undefined) return existing;
+    return this.add(spec);
+  }
+
+  clear(): void { this.lifecycle.abort(); this.triggers.clear(); }
+
+  /**
+   * LLM-judge every enabled condition on `surface` against the current turn and return the distinct
+   * triggers that fired, each with the set of `kinds` whose conditions matched (a trigger can carry
+   * more than one kind on the same surface — `retract` and `followup` both read the agent response —
+   * so the caller resolves the delivery) AND `matched` — the specific condition(s) that fired, with
+   * the classifier's one-line reason for each. Without `matched`, a trigger with several conditions on
+   * the same kind is indistinguishable in the trace from one with a single condition — "it fired" tells
+   * you nothing about *why*, which is the question a false-positive post-mortem actually asks. Both
+   * sides of the exchange are passed: `subject` is judged, `context` is what it is paired with — many
+   * conditions are relational ("disputes the previous answer") and can only be judged from the pair. No
+   * LLM call when there are no candidate conditions or the subject is empty.
+   */
+  async evaluate(
+    surface:      TriggerSurface,
+    subject:      { label: string; text: string },
+    context:      { label: string; text: string },
+    signal:       AbortSignal,
+    turnProvider: string,
+  ): Promise<{ trigger: Trigger; kinds: TriggerKind[]; matched: FiredCondition[] }[]> {
+    // Candidate key is `${triggerId}#${conditionIndex}` — addressing conditions by index is fine
+    // because evaluation is per-turn and the trigger set is stable for its duration. The surface a
+    // condition belongs to is derived from its `kind` (ephemeral/contextual→user, retract/followup→agent).
+    const candidates = this.all()
+      .filter(t => t.enabled !== false)
+      .flatMap(t => t.conditions
+        .map((c, i) => ({ triggerId: t.id, key: `${t.id}#${i}`, index: i, kind: c.kind, rule: c.rule }))
+        .filter(c => surfaceOfKind(c.kind) === surface));
+    if (candidates.length === 0 || subject.text === '') return [];
+
+    const res = await this.services.singleTurn({
+      provider: await this.resolveClassifierProvider(turnProvider),
+      signal,
+      system:
+        'You are a trigger classifier for a conversational assistant. Below is the current exchange — ' +
+        'the user message and the assistant message, in chronological order and clearly labelled — ' +
+        `followed by a list of conditions. Evaluate each condition against the "${subject.label}". The ` +
+        `"${context.label}" is the message it is paired with; use it fully whenever a condition is ` +
+        'relational (refers to what was asked, answered, disputed, or repeated). Fire a condition when, ' +
+        `reading the "${subject.label}" in light of the "${context.label}", it holds. Return ONLY a JSON ` +
+        'object mapping each condition id (the bracketed value) to an object {"match": true|false, ' +
+        '"why": "<one short sentence citing the specific evidence>"}. No other text.',
+      prompt:
+        `${context.label} (earlier):\n${context.text === '' ? '(none)' : clip(context.text)}\n\n` +
+        `${subject.label} (later — evaluate the conditions against THIS):\n${clip(subject.text)}\n\n` +
+        `Conditions:\n${candidates.map(c => `[${c.key}] ${c.rule}`).join('\n')}`,
+    });
+
+    let verdicts: Record<string, unknown> = {};
+    try {
+      const m = res.text.match(/\{[\s\S]*\}/);
+      verdicts = m ? JSON.parse(m[0]) : {};
+    } catch {
+      console.warn(`[triggers] ${surface} classifier returned non-JSON:`, res.text.slice(0, 200));
+      return [];
+    }
+
+    // Group fired conditions back to their triggers, keeping each matched condition's index/rule/why
+    // alongside the distinct kinds that matched (kinds is a projection of matched, kept for callers
+    // that only need delivery routing).
+    const firedByTrigger = new Map<string, FiredCondition[]>();
+    for (const c of candidates) {
+      const v = verdicts[c.key] as { match?: unknown; why?: unknown } | boolean | undefined;
+      const isMatch = typeof v === 'object' && v !== null ? v.match === true : v === true;
+      if (!isMatch) continue;
+      const why = typeof v === 'object' && v !== null && typeof v.why === 'string' ? v.why : undefined;
+      const list = firedByTrigger.get(c.triggerId) ?? [];
+      list.push({ index: c.index, kind: c.kind, rule: c.rule, ...(why !== undefined ? { why } : {}) });
+      firedByTrigger.set(c.triggerId, list);
+    }
+    return [...firedByTrigger].flatMap(([id, matched]) => {
+      const trigger = this.triggers.get(id);
+      return trigger ? [{ trigger, kinds: [...new Set(matched.map(m => m.kind))], matched }] : [];
+    });
+  }
+
+  private async casMutate(doc: Trigger, mutate: (cur: Trigger) => Trigger): Promise<Trigger> {
+    let cur = doc;
+    for (;;) {
+      const next = mutate(cur);
+      const r = await this.store.cas(cur.id, cur.version, next);
+      if (r.ok) { this.triggers.set(next.id, next); return next; }
+      const fresh = await this.store.get(cur.id);
+      if (fresh === null) {
+        await this.store.set(next.id, next);
+        this.triggers.set(next.id, next);
+        return next;
+      }
+      cur = fresh;
+    }
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,373 @@
+import { PLUGIN_API_VERSION } from '@matatbread/matbot-plugin-api';
+import type { MatbotPluginSpec, MatbotMachine, Store, Message, MessageContent } from '@matatbread/matbot-plugin-api';
+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';
+
+/** 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
+ *  (if it said) why. */
+interface FiredSource {
+  id:      string;
+  matched: FiredCondition[];
+}
+
+declare module '@matatbread/matbot-plugin-api' {
+  interface MatbotServices {
+    /** The live trigger set (data-driven hooks). Registered by setupTriggers; consumed by plugins
+     *  that seed built-in triggers (e.g. cognition). Its presence is the "triggers wired" signal. */
+    Triggers?: Triggers;
+  }
+}
+
+/** One-shot reachability probe for a pinned provider, used only when forming installationMessage
+ *  (install/reload) — never on the hot path. Fails soft: a thrown error becomes `{ ok: false }`. */
+async function testProvider(services: MatbotMachine, provider: string): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await services.singleTurn({ provider, prompt: 'Reply with "ok".', signal: AbortSignal.timeout(15000) });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// Multiple fired triggers' results are joined with a separator.
+const JOIN = '\n\n---\n\n';
+
+// Out-of-band tool output is delivered by folding it onto the user turn (user phase / agent retract)
+// or as a robo turn (agent followup). Without a provenance marker the model reads it as the user
+// speaking — observed in testing: the model's own thinking said "the user wants me to follow the
+// skill…" about a system-injected directive. The dispatcher stays a dumb transport (it injects
+// whatever a tool yields); this fence is the triggers plugin's own framing, marking the payload as
+// system-supplied so the model treats it as context to act on, not a user utterance. A tool whose
+// result is already a directive (e.g. `skill_action(use)`) self-frames *what* to do; the fence adds
+// *who* supplied it — orthogonal, composes cleanly.
+function fence(body: string): string {
+  return `[Additional context — supplied by the system, not part of the user's message. ` +
+    `Take it into account when responding.]\n\n${body}\n\n[End of additional context.]`;
+}
+
+// A durable trace of a user-phase injection. For `ephemeral-inject` the injected `text` is never
+// otherwise persisted, so without this a post-mortem can't see what the system fed the model before it
+// answered; for `durable-inject` the text IS persisted (folded onto the user turn), so `text` is
+// omitted and the marker records only WHICH condition fired and why. LLM-invisible like any marker; a
+// frontend may ignore it (diagnostic, not user-facing). `triggers` are the firing sources (id +
+// matched conditions). (The agent-phase injections are traced elsewhere: a retract redo's context by
+// the core retraction marker, and a `followup` resubmit by its persisted robo turn.)
+function injectionMarker(event: 'ephemeral-inject' | 'durable-inject', triggers: FiredSource[], text?: string): MessageContent {
+  return { type: 'marker', creator: 'triggers', data: { event, surface: 'user', triggers, ...(text !== undefined ? { text } : {}) } };
+}
+
+// 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.
+const RETRACTION_CREATOR = 'matbot-retraction';
+
+// Suppression is NEVER silent: when a guard holds a trigger back, it leaves this marker naming the
+// `cause` (a machine tag), a human `reason`, and the triggers (id + matched conditions) — so "why
+// didn't it fire?" is answerable from the session months later rather than from a remembered heuristic.
+// `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';
+function suppressedMarker(cause: SuppressCause, reason: string, triggers: FiredSource[]): MessageContent {
+  return { type: 'marker', creator: 'triggers', data: { event: 'suppressed', cause, reason, triggers } };
+}
+function retractFiredMarker(triggers: FiredSource[]): MessageContent {
+  return { type: 'marker', creator: 'triggers', data: { event: 'retract-fired', triggers } };
+}
+
+// True when the latest turn is a retract-redo: a `matbot-retraction` marker sits after the last genuine
+// (non-robo) user message — i.e. this user message was already processed on the original attempt, so
+// user-phase (ephemeral/contextual) triggers and their side effects already fired. Re-firing them on the
+// redo is the duplicate-side-effect bug; skip them.
+function isRetractRedo(messages: Message[]): boolean {
+  const lastUser = messages.findLastIndex(m => m.role === 'user' && !m.content.every(c => c.origin === 'robo'));
+  if (lastUser < 0) return false;
+  return messages.slice(lastUser + 1).some(m => m.content.some(c => c.type === 'marker' && c.creator === RETRACTION_CREATOR));
+}
+
+// Retract trigger ids that were ACTIVE on the PREVIOUS turn (the region between the second-to-last and
+// last genuine user messages) — active meaning the rule either fired a retract OR was itself held off by
+// the convergence guard. Counting suppressions too is what makes the guard *converge* rather than
+// oscillate: a rule that keeps matching stays held off turn after turn (each suppression re-arms the
+// guard), instead of firing every other turn because a suppressed turn left no trace. It un-sticks only
+// when the rule genuinely stops matching for a turn (no marker), after which it may fire fresh. A
+// well-behaved rule self-terminates and never lands here.
+function retractActiveLastTurn(messages: Message[]): Set<string> {
+  const userIdxs: number[] = [];
+  messages.forEach((m, i) => { if (m.role === 'user' && !m.content.every(c => c.origin === 'robo')) userIdxs.push(i); });
+  const cur = userIdxs.at(-1);
+  if (cur === undefined) return new Set();
+  const prev = userIdxs.at(-2) ?? -1;
+  const ids = new Set<string>();
+  for (let i = prev + 1; i < cur; i++) {
+    for (const c of messages[i]!.content) {
+      if (c.type !== 'marker' || c.creator !== 'triggers') continue;
+      const d = c.data as { event?: unknown; cause?: unknown; triggers?: unknown };
+      const active = d?.event === 'retract-fired' || (d?.event === 'suppressed' && d?.cause === 'retract-convergence');
+      if (active && Array.isArray(d.triggers)) {
+        for (const t of d.triggers) {
+          if (typeof t === 'object' && t !== null && typeof (t as { id?: unknown }).id === 'string') ids.add((t as { id: string }).id);
+        }
+      }
+    }
+  }
+  return ids;
+}
+
+function textOf(msg: Message | undefined): string {
+  return msg?.content.filter(c => c.type === 'text').map(c => c.text).join('\n') ?? '';
+}
+
+/**
+ * Wire the triggers subsystem: build the {@link TriggerManager}, load persisted triggers, register
+ * the `Triggers` service and the `trigger_action` tool, then install the two evaluation hooks:
+ *
+ *   user  — a `screen` hook (pre-response) that judges `user`-phase conditions against the incoming
+ *           message, invokes each fired trigger's tool, and delivers the result per the fired
+ *           condition's `kind`: `ephemeral` (inject for this turn only, never persisted) or
+ *           `contextual` (fold DURABLY onto the user message — persisted + visible — so it updates
+ *           the conversation rather than informing one answer).
+ *   agent — a `followup` hook (post-commit) that judges agent-surface conditions against the
+ *           assistant's response, invokes each fired trigger's tool, and delivers the result per the
+ *           fired condition's `kind`: `retract` (discard the response and re-run with the result
+ *           injected) or `followup` (keep the response and resubmit the result as a robo turn).
+ *
+ * Both phases fence the injected payload (see {@link fence}) so the model reads it as system-supplied
+ * context, not a user utterance.
+ *
+ * Returns the manager so a specialization (a node watcher, say) could attach to the same instance.
+ * Uses only web-platform APIs.
+ */
+export async function setupTriggers(services: MatbotMachine): Promise<TriggerManager> {
+  // Idempotent on the registered service, not a module flag (a re-import would reset a flag; the
+  // registry persists for the process) — a second setupTriggers hands back the live manager.
+  if (services.Triggers) return services.Triggers as TriggerManager;
+
+  const store   = services.createStore<Trigger>('triggers') as Store<Trigger>;
+  const manager = new TriggerManager(store, services);
+  await manager.load();
+  // Re-read after a deferred StorageBackend swap lands: the new backend's `triggers` namespace replaces
+  // the old in-memory set. No `replay` — the initial load is the boot load above; this reacts only to
+  // future swaps. Ends with the manager (teardown aborts manager.signal).
+  services.mounted.consume({ key: 'StorageBackend', signal: manager.signal }, () => void manager.load());
+  await services.register('Triggers', manager);
+
+  services.tools.register(createTriggerActionTool(manager));
+  services.tools.register(createTriggersConfigTool(services));
+
+  // user phase — pre-response. Judges the incoming user message and delivers each fired trigger's tool
+  // result by its kind: `ephemeral` informs this response only; `contextual` folds durably onto the
+  // user turn so it persists into the conversation.
+  services.hooks.register({
+    on: 'screen',
+    async handler(ctx) {
+      const lastUser = ctx.session.messages.findLast(l => l.role === 'user');
+      // Skip our own agent-phase robo resubmissions — they are not real user turns.
+      if (!lastUser || lastUser.content.every(c => c.origin === 'robo')) return;
+
+      // Guard: a retract-redo re-runs this same user turn. The user-phase (ephemeral/contextual)
+      // triggers already fired — and their side effects (e.g. remember_fact's store write, or a
+      // contextual fold persisted onto the user message) already happened — on the original attempt,
+      // so re-firing here double-applies them. Hold off, and record why (suppression is never silent).
+      // The redo still gets the retract correction via the injected context.
+      if (isRetractRedo(ctx.session.messages)) {
+        return { markers: [suppressedMarker('user-redo', 'user-phase triggers held off: retract-redo (user message already processed on the original attempt)', [])] };
+      }
+
+      const fired = await manager.evaluate(
+        'user',
+        { label: 'latest user message', text: textOf(lastUser) },
+        { label: 'preceding assistant message', text: textOf(ctx.session.messages.findLast(
+          l => l.role === 'assistant' && l.content.some(c => c.type === 'text'),
+        )) },
+        ctx.signal,
+        ctx.config.provider,
+      );
+      if (fired.length === 0) return;
+
+      // Partition fired triggers' output by delivery. A trigger can carry both kinds on this surface;
+      // if any `contextual` condition fired the output goes durable, since a durable fold is also sent
+      // on this very turn (it lands in the user message before the provider call) — it is a superset of
+      // ephemeral, so "contextual dominates" loses nothing, mirroring retract-over-followup on the
+      // agent surface. Markers are collected regardless — they persist whichever path runs.
+      const ephemeralBodies:  string[]         = [];
+      const ephemeralSources: FiredSource[]    = [];
+      const durableBodies:    string[]         = [];
+      const durableSources:   FiredSource[]    = [];
+      const markers:          MessageContent[] = [];
+      for (const { trigger, kinds, matched } of fired) {
+        const out = await dispatchTrigger(services, trigger, { session: ctx.session, signal: ctx.signal, provider: ctx.config.provider, ...(ctx.prompt !== undefined ? { prompt: ctx.prompt } : {}) });
+        if (out.hadResult) {
+          if (kinds.includes('contextual')) {
+            durableBodies.push(renderResult(out.result));
+            durableSources.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'contextual') });
+          } else {
+            ephemeralBodies.push(renderResult(out.result));
+            ephemeralSources.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'ephemeral') });
+          }
+        }
+        markers.push(...out.markers);
+      }
+      // Trace each injection. The ephemeral text is never otherwise persisted, so the marker carries it;
+      // the durable text rides the user message itself, so its marker records only the firing sources.
+      if (ephemeralBodies.length > 0) markers.push(injectionMarker('ephemeral-inject', ephemeralSources, ephemeralBodies.join(JOIN)));
+      if (durableBodies.length   > 0) markers.push(injectionMarker('durable-inject',   durableSources));
+      if (ephemeralBodies.length === 0 && durableBodies.length === 0 && markers.length === 0) return;
+
+      return {
+        // The dispatcher appends markers to the session AND emits them live (consistent draw/reload).
+        // `ephemeral` informs only this turn; `durable` folds onto the user turn (origin: 'robo'),
+        // persists, and is carried live as a robo-user event.
+        ...(markers.length         > 0 ? { markers } : {}),
+        ...(ephemeralBodies.length > 0 ? { ephemeral: [{ type: 'text', text: fence(ephemeralBodies.join(JOIN)) }] } : {}),
+        ...(durableBodies.length   > 0 ? { durable:   [{ type: 'text', text: fence(durableBodies.join(JOIN)), origin: 'robo' as const }] } : {}),
+      };
+    },
+  });
+
+  // agent phase — post-commit. Judges the assistant's response (with the preceding user message as
+  // relational context), invokes fired triggers, and delivers each one per its condition's `kind`:
+  //   retract  — the response was WRONG: pop it and re-run the user turn with the output injected.
+  //   followup — the response STANDS but needs a steer: keep it, resubmit a robo turn carrying the
+  //              output (so the response remains in context for the steer to make sense).
+  // Skips our own redos/resubmits (resubmitDepth > 0) so a fired trigger can't re-fire on its output.
+  services.hooks.register({
+    on: 'followup',
+    async handler(ctx) {
+      if (ctx.resubmitDepth > 0) return;
+
+      const fired = await manager.evaluate(
+        'agent',
+        { label: 'assistant response', text: textOf(ctx.session.messages.findLast(
+          l => l.role === 'assistant' && l.content.some(c => c.type === 'text'),
+        )) },
+        { label: 'preceding user message', text: textOf(ctx.session.messages.findLast(l => l.role === 'user')) },
+        ctx.signal,
+        ctx.config.provider,
+      );
+      if (fired.length === 0) return;
+
+      // Convergence guard: a retract rule that already retracted on the PREVIOUS turn and is about to
+      // again has not converged (the redo didn't dissolve its condition). Hold those rules off so a
+      // mis-tuned retract can't pop-and-redo every turn forever. A well-behaved rule self-terminates
+      // (its redo cures the defect, so it won't fire next turn) and never lands here.
+      const heldOff = retractActiveLastTurn(ctx.session.messages);
+
+      // Partition fired triggers' output by their kind. A trigger can carry both retract and followup
+      // conditions; if any retract condition fired, the trigger is treated as retract (a wrong answer
+      // can't be merely steered). Markers are collected regardless — they persist whichever path runs.
+      const retractBodies:   string[]         = [];
+      const retractSources:  FiredSource[]    = [];
+      const followupBodies:  string[]         = [];
+      const followupSources: FiredSource[]    = [];
+      const suppressed:      FiredSource[]    = [];
+      const markers:         MessageContent[] = [];
+      for (const { trigger, kinds, matched } of fired) {
+        if (kinds.includes('retract') && heldOff.has(trigger.id)) {
+          suppressed.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'retract') });
+          continue;
+        }
+        const out = await dispatchTrigger(services, trigger, { session: ctx.session, signal: ctx.signal, provider: ctx.config.provider, ...(ctx.prompt !== undefined ? { prompt: ctx.prompt } : {}) });
+        if (out.hadResult) {
+          if (kinds.includes('retract')) {
+            retractBodies.push(renderResult(out.result));
+            retractSources.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'retract') });
+          } else {
+            followupBodies.push(renderResult(out.result));
+            followupSources.push({ id: trigger.id, matched: matched.filter(m => m.kind === 'followup') });
+          }
+        }
+        markers.push(...out.markers);
+      }
+      // Suppression is never silent — record which rules were held off and why.
+      if (suppressed.length > 0) {
+        markers.push(suppressedMarker('retract-convergence', 'retract held off: this rule was active on the previous turn and is still matching (non-converging)', suppressed));
+      }
+
+      // Retract dominates: if any trigger judged the response WRONG, the response is discarded, so a
+      // steer that critiques it has lost its subject — skip the followup bodies this turn. That skip is
+      // a suppression too, so it leaves a `suppressed` marker (not just a log): a followup that "didn't
+      // fire" because a retract preempted it is answerable from the session. The redo's injected context
+      // is recorded by the core retraction marker; the `retract-fired` marker lets the next turn's
+      // convergence guard see this firing.
+      if (retractBodies.length > 0) {
+        if (followupBodies.length > 0) {
+          markers.push(suppressedMarker('followup-shadowed', 'followup steer skipped: a retract on the same turn supersedes the response it would critique', followupSources));
+        }
+        markers.push(retractFiredMarker(retractSources));
+        return {
+          retractAndRerun: { context: [{ type: 'text', text: fence(retractBodies.join(JOIN)) }] },
+          markers,
+        };
+      }
+      if (followupBodies.length > 0) {
+        return {
+          resubmit: { content: [{ type: 'text', origin: 'robo', text: fence(followupBodies.join(JOIN)) }] },
+          ...(markers.length > 0 ? { markers } : {}),
+        };
+      }
+      // No model-facing result from any trigger — only markers (silent side-effects), if any.
+      return markers.length > 0 ? { markers } : undefined;
+    },
+  });
+
+  return manager;
+}
+
+/**
+ * The cross-runtime triggers plugin: stored conditions that, when an LLM classifier judges them
+ * matched, invoke a tool. CRUD via `trigger_action`; the `agent`/`user` conditions are evaluated by a
+ * classifier provider (pinned via `triggers_config`, else the turn's own provider). Runs in both Node
+ * and the browser.
+ */
+export function createTriggersPlugin(): MatbotPluginSpec {
+  let manager:  TriggerManager  | undefined;
+  let captured: MatbotMachine  | undefined;   // captured in setup() so installationMessage() can probe
+
+  const base =
+    'Triggers are active (trigger_action). A trigger fires a tool when an LLM classifier judges one of ' +
+    'its conditions matched against the current turn.';
+
+  return {
+    apiVersion: PLUGIN_API_VERSION,
+    manifest: {
+      description: 'Data-driven hooks: stored conditions that invoke a tool when an LLM classifier judges them matched. CRUD via trigger_action. Cross-runtime (node + browser).',
+    },
+
+    async installationMessage() {
+      if (!captured) return base;
+      const pinned    = await captured.settings().get<string>('classifierProvider');
+      const available = [...captured.providers.keys()];
+      const legacy    = captured.providers.has('skills-classifier');
+      if (pinned === undefined) {
+        return base +
+          (legacy
+            ? '\n\nThe classifier uses the provider "skills-classifier" (the legacy default present in this install).'
+            : '\n\nNo classifier provider is pinned, so the classifier uses whatever provider the current turn ' +
+              'runs on — triggers work out of the box.') +
+          ' To pin a small/fast model instead, use the triggers_config tool (action "set"). ' +
+          `Available providers: ${available.join(', ') || '(none)'}.`;
+      }
+      const probe = await testProvider(captured, pinned);
+      return base +
+        `\n\nThe classifier is pinned to "${pinned}" (triggers_config), which ` +
+        (probe.ok
+          ? 'responded to a test prompt.'
+          : `did NOT respond: ${probe.error}. It falls back to the turn's own provider until fixed.`);
+    },
+
+    async setup(services) {
+      captured = services;
+      manager  = await setupTriggers(services);
+    },
+
+    async teardown() {
+      manager?.clear();
+    },
+  };
+}
+
+export const plugin: MatbotPluginSpec = createTriggersPlugin();

package/src/tools.ts

@@ -0,0 +1,230 @@
+import type { Tool, ToolExecutor, ToolContext, ToolEvent, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type { TriggerManager } from './manager.js';
+import type { TriggerCondition, TriggerKind } from './types.js';
+
+const KINDS: readonly TriggerKind[] = ['ephemeral', 'contextual', 'retract', 'followup'];
+const isKind = (x: unknown): x is TriggerKind => typeof x === 'string' && (KINDS as readonly string[]).includes(x);
+
+const GUIDANCE =
+  'A trigger is a data-driven hook: a list of `conditions` and the single tool call (`invoke`) to ' +
+  'make when ANY condition matches. The conditions are the OR — different ways to recognise the ' +
+  'situation — and the invocation is the one consequence.\n\n' +
+  'Each condition has a `kind` and a `rule`:\n' +
+  '• The `rule` is a CONDITION on the FORM or SENTIMENT of a message, NOT its topic (topical ' +
+  'relevance is found by search, so keyword/entity rules are redundant noise — do not write them). ' +
+  'Phrase it as a single LLM-judged rubric "MATCH if the message is …; DO NOT MATCH if …".\n' +
+  '• `kind` fixes WHAT is judged and WHAT happens when it matches:\n' +
+  '   - "ephemeral": judge the USER MESSAGE (e.g. frustration, a fact worth surfacing now); run the ' +
+  'tool and inject its output into the response about to be written — for THIS turn only, not kept.\n' +
+  '   - "contextual": judge the USER MESSAGE; run the tool and fold its output DURABLY onto the user ' +
+  "turn, so it persists into the conversation and every later turn sees it. Choose ephemeral vs " +
+  'contextual by whether a match means "use this for this answer" vs "this should become part of the ' +
+  'session".\n' +
+  '   - "retract": judge the ASSISTANT RESPONSE; the response is WRONG, so discard it and regenerate ' +
+  'the turn with the output as context (e.g. a corrected field name invalidates everything downstream).\n' +
+  '   - "followup": judge the ASSISTANT RESPONSE; the response STANDS but needs a steer or ' +
+  '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 ' +
+  '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` ' +
+  '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.)';
+
+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: 'remove'; id: string };
+
+// 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 =>
+    c !== null && typeof c === 'object' &&
+    isKind((c as { kind?: unknown }).kind) &&
+    typeof (c as { rule?: unknown }).rule === 'string');
+}
+
+export function createTriggerActionTool(manager: TriggerManager): Tool {
+  const executor: ToolExecutor = {
+    async *execute(input: unknown, _ctx: ToolContext): AsyncIterable<ToolEvent> {
+      const args = input as Partial<TriggerActionInput> & { action?: string };
+
+      switch (args.action) {
+        case 'list': {
+          yield { type: 'result', value: { triggers: manager.all() } };
+          return;
+        }
+
+        case 'query': {
+          const a = args as Extract<TriggerActionInput, { action: 'query' }>;
+          yield { type: 'result', value: { triggers: manager.query({
+            ...(typeof a.tool === 'string' ? { tool: a.tool } : {}),
+            ...(a.params !== undefined ? { params: a.params } : {}),
+          }) } };
+          return;
+        }
+
+        case 'get': {
+          const { id } = args as Extract<TriggerActionInput, { action: 'get' }>;
+          if (!id) { yield { type: 'error', message: 'action "get" requires "id".' }; return; }
+          const t = manager.get(id);
+          if (!t) { yield { type: 'error', message: `Trigger not found: "${id}"` }; return; }
+          yield { type: 'result', value: t };
+          return;
+        }
+
+        case 'add': {
+          const a = args as Extract<TriggerActionInput, { action: 'add' }>;
+          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; }
+          const t = await manager.add({
+            conditions: a.conditions,
+            invoke:     { tool: a.tool, ...(a.params !== undefined ? { params: a.params } : {}) },
+            ...(a.enabled !== undefined ? { enabled: a.enabled } : {}),
+          });
+          yield { type: 'result', value: { id: t.id } };
+          return;
+        }
+
+        case 'update': {
+          const a = args as Extract<TriggerActionInput, { action: 'update' }>;
+          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; }
+          const t = await manager.update(a.id, {
+            ...(a.conditions !== undefined ? { conditions: a.conditions } : {}),
+            ...(a.tool !== undefined || a.params !== undefined
+              ? { invoke: { tool: a.tool ?? manager.get(a.id)?.invoke.tool ?? '', ...(a.params !== undefined ? { params: a.params } : {}) } }
+              : {}),
+            ...(a.enabled !== undefined ? { enabled: a.enabled } : {}),
+          });
+          if (t === undefined) { yield { type: 'error', message: `Trigger not found: "${a.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; }
+          const ok = await manager.remove(id);
+          if (!ok) { yield { type: 'error', message: `Trigger not found: "${id}"` }; return; }
+          yield { type: 'result', value: { id } };
+          return;
+        }
+
+        default:
+          yield { type: 'error', message: `Unknown action "${String(args.action)}". Expected one of: list, query, get, add, update, remove.` };
+      }
+    },
+  };
+
+  return {
+    name: 'trigger_action',
+    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, or delete one.\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" +
+      '```',
+    inputSchema: {
+      type:       'object',
+      required:   ['action'],
+      properties: {
+        action:     { type: 'string', enum: ['list', 'query', 'get', 'add', 'update', 'remove'], description: 'The operation to perform.' },
+        id:         { type: 'string', description: 'Trigger id. Required for get/update/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: 'Name of the tool to invoke when a condition matches. Required for add.' },
+        params:     { type: 'object', description: 'Params passed verbatim as the invoked tool\'s input.' },
+        enabled:    { type: 'boolean', description: 'Set false to keep but disable the trigger.' },
+      },
+    },
+    executor,
+  };
+}
+
+/**
+ * Get/set which provider the trigger classifier uses to judge conditions. The provider is an alias for
+ * one of the already-configured providers, not a new one: unset, the classifier uses the current turn's
+ * own provider (so triggers work with zero config); set it to pin a small/fast model. Resolved per
+ * evaluation, so a change takes effect on the next turn without a restart.
+ */
+export function createTriggersConfigTool(services: MatbotMachine): Tool {
+  const KEY = 'classifierProvider';
+  const executor: ToolExecutor = {
+    async *execute(input: unknown, _ctx: ToolContext): AsyncIterable<ToolEvent> {
+      const args      = input as { action?: string; provider?: string };
+      const settings  = services.settings();
+      const available = [...services.providers.keys()];
+      switch (args.action) {
+        case 'get': {
+          const pinned = await settings.get<string>(KEY);
+          yield { type: 'result', value: { classifierProvider: pinned ?? null, available } };
+          return;
+        }
+        case 'set': {
+          if (!args.provider) { yield { type: 'error', message: 'action "set" requires "provider".' }; return; }
+          if (!services.providers.has(args.provider)) {
+            yield { type: 'error', message: `Unknown provider "${args.provider}". Configured providers: ${available.join(', ') || '(none)'}.` };
+            return;
+          }
+          await settings.set(KEY, args.provider);
+          yield { type: 'result', value: { classifierProvider: args.provider } };
+          return;
+        }
+        case 'clear': {
+          await settings.delete(KEY);
+          yield { type: 'result', value: { classifierProvider: null } };
+          return;
+        }
+        default:
+          yield { type: 'error', message: `Unknown action "${String(args.action)}". Expected one of: get, set, clear.` };
+      }
+    },
+  };
+
+  return {
+    name: 'triggers_config',
+    description:
+      'Configure the triggers subsystem. Currently one setting: `classifierProvider` — which configured ' +
+      '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" +
+      '```',
+    inputSchema: {
+      type:       'object',
+      required:   ['action'],
+      properties: {
+        action:   { type: 'string', enum: ['get', 'set', 'clear'], description: 'The operation to perform.' },
+        provider: { type: 'string', description: 'Name of an already-configured provider — required for "set".' },
+      },
+    },
+    executor,
+  };
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+/**
+ * A trigger is a data-driven hook: a set of natural-language conditions and the single tool call to
+ * make when any of them is judged to match. The conditions are the OR — many ways to recognise the
+ * situation — and `invoke` is the one consequence. There is no skill coupling: a trigger names a
+ * tool, not a skill, so firing a skill is just `invoke: skill_action({ action: 'use', … })` like
+ * any other tool call (`use` applies the skill as a directive; `load` returns raw content, which is
+ * for reading/editing, not firing). What the model sees afterwards is decided observationally — see dispatch.ts.
+ */
+
+/**
+ * What a trigger does when one of its conditions matches. A single discriminator: it fixes the
+ * surface judged, the hook, AND how the fired tool's output reaches the model — because those are
+ * not independent (delivery determines surface). The four are disjoint and exhaustive, two per
+ * surface:
+ *
+ *  `ephemeral`  — judge the USER message (pre-response `screen` hook); run the tool and inject its
+ *    output for THIS turn only — never persisted, byte-stable prefix preserved. The one-shot "route
+ *    knowledge in for this answer" case (was named `augment`).
+ *  `contextual` — judge the USER message (pre-response `screen` hook); run the tool and fold its
+ *    output DURABLY onto the user turn (an `origin: 'robo'` block, persisted + visible), so it
+ *    updates the conversation rather than informing one answer. Use when a match means "this should
+ *    become part of the session", not "correct just this turn". The durable twin of `ephemeral`.
+ *  `retract`    — judge the ASSISTANT response (post-commit `followup` hook); the response is treated
+ *    as WRONG — pop it into a retraction marker and re-run the user turn with the output injected, so
+ *    the bad answer does NOT remain (e.g. "the field is `pgdwell`, not `dwell`": everything built on
+ *    the wrong field is void, so regenerate from scratch with the correction).
+ *  `followup`   — judge the ASSISTANT response (post-commit `followup` hook); the response STANDS but
+ *    warrants a steer or verification — keep it and resubmit the output as a robo turn, so the
+ *    response stays in context for the steer to make sense (Inner Voice / Verify Assumptions /
+ *    Bicameral — critiques *of* the standing answer, meaningless without it).
+ *
+ * The author picks the kind because only they know whether a match means "read this for now" /
+ * "remember this from now on" / "this is wrong" / "look again".
+ */
+export type TriggerKind = 'ephemeral' | 'contextual' | 'retract' | 'followup';
+
+/** The conversational surface a `kind` is judged against, and which hook does the judging:
+ *  `ephemeral`/`contextual` read the user message (pre-response `screen` hook); `retract`/`followup`
+ *  read the assistant response (post-commit `followup` hook). Derived from `kind` — see
+ *  {@link surfaceOfKind}. */
+export type TriggerSurface = 'user' | 'agent';
+
+export function surfaceOfKind(kind: TriggerKind): TriggerSurface {
+  return kind === 'ephemeral' || kind === 'contextual' ? 'user' : 'agent';
+}
+
+/** A trigger condition: a `kind` (what a match does, and the surface it's judged on) plus a `rule`. */
+export interface TriggerCondition {
+  kind: TriggerKind;
+  /** A single LLM-judged rubric, e.g. "MATCH if …; DO NOT MATCH if …", judged against the turn. */
+  rule: string;
+}
+
+/** One condition the classifier judged matched, for tracing *why* a trigger fired (not just that it
+ *  did): `index` addresses it within the owning trigger's `conditions` array, `rule` is the rubric
+ *  text at the time of evaluation, and `why` is the classifier's one-line justification (absent if it
+ *  didn't supply one). */
+export interface FiredCondition {
+  index: number;
+  kind:  TriggerKind;
+  rule:  string;
+  why?:  string;
+}
+
+/** The tool call a matched trigger makes. `params` is passed verbatim as the tool's input. */
+export interface TriggerInvoke {
+  tool:    string;
+  params?: unknown;
+}
+
+export interface Trigger {
+  id:         string;
+  version:    string;
+  conditions: TriggerCondition[];
+  invoke:     TriggerInvoke;
+  /** Absent ⇒ enabled. A disabled trigger is kept but never evaluated. */
+  enabled?:   boolean;
+  createdAt:  string;
+  updatedAt:  string;
+}
+
+/** Fields a caller supplies when creating or replacing a trigger; identity/versioning is the store's. */
+export interface TriggerSpec {
+  conditions: TriggerCondition[];
+  invoke:     TriggerInvoke;
+  enabled?:   boolean;
+}
+
+/**
+ * The registry interface other plugins consume (`services.Triggers`) to create triggers without
+ * knowing who owns the store or the hooks. CRUD only — evaluation and dispatch are internal to the
+ * triggers plugin, which owns the hooks that drive them.
+ */
+export interface Triggers {
+  all(): Trigger[];
+  get(id: string): Trigger | undefined;
+  /** Triggers whose invocation matches the filter — `tool` (if given) equals `invoke.tool`, `params`
+   *  (if given) deep-equals `invoke.params`. The "which trigger(s) fire tool X" lookup. */
+  query(filter: { tool?: string; params?: unknown }): Trigger[];
+  add(spec: TriggerSpec): Promise<Trigger>;
+  update(id: string, patch: Partial<TriggerSpec>): Promise<Trigger | undefined>;
+  remove(id: string): Promise<boolean>;
+  /** Seed idempotently: no-op (returns the existing trigger) when one with the same `invoke`
+   *  (tool + params) is already stored. Identity is the invocation, since triggers carry no name. */
+  importIfAbsent(spec: TriggerSpec): Promise<Trigger>;
+}