@owlmeans/bot-agent 0.1.18-rc.2 → 0.1.18

package/README.md

@@ -2,17 +2,19 @@
 
 The bridge between an OwlMeans chat bot and an `@owlmeans/agent` agent. `botAgentPlugin` hands the
 agent ONE bot update: the message — platform, chat, sender, the text, the replied-to text — and the
-keyword groups it matched, with their instructions, become the agent's context; the bot's actions
-(`reply`, `delete`, `warn`, `mute`, `ban`, `react`) become its tools, limited to what the platform
-supports and the caller allows. A tool never throws: it answers `done`, or what went wrong.
+instructions the handler passes (those of the application's own keyword groups the message matched)
+become the agent's context; the bot's actions (`reply`, `delete`, `warn`, `mute`, `ban`, `react`)
+become its tools, limited to what the platform supports and the caller allows, each recording the
+handler's `ref`. A tool never throws: it answers `done`, or what went wrong.
 
-It stores, receives and sends nothing itself — the actions are `@owlmeans/server-bot`'s
-`BotActions`, which record every call as activity.
+It stores, receives, matches and sends nothing itself — the handler matches the message against the
+application's records, and the actions are `@owlmeans/server-bot`'s `BotActions`, which record every
+call as activity.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/bot-agent@^0.1.18-rc.2
+bun add @owlmeans/bot-agent@^0.1.18
 ```
 
 `@owlmeans/agent` and `@langchain/core` are peers.
@@ -20,14 +22,20 @@ bun add @owlmeans/bot-agent@^0.1.18-rc.2
 ## Usage
 
 ```typescript
-import { BotActionKind } from '@owlmeans/bot'
+import { BotActionKind, botTextHelper } from '@owlmeans/bot'
 import { botAgentHelper, botAgentPlugin } from '@owlmeans/bot-agent'
 import { botHandler } from '@owlmeans/server-bot'
 
-export const moderate = botHandler('moderate', async (update, bot) => {
-  if (update.matches.length === 0) return
-  const agent = makeModeratorAgent()                    // your makeAgentModel(…) factory
-  agent.use(botAgentPlugin({ update, bot, allow: [BotActionKind.Delete, BotActionKind.Reply] }))
+export const moderate = botHandler('moderate', async (update, bot, ctx) => {
+  const text = update.message?.text ?? ''
+  const groups = (await keywordGroupsOf(ctx, update.scope))     // the application's own records
+    .filter(group => botTextHelper.matched(text, group.keywords).length > 0)
+  if (groups.length === 0) return
+  const agent = makeModeratorAgent()                            // your makeAgentModel(…) factory
+  agent.use(botAgentPlugin({
+    update, bot, ref: groups[0].id, instruction: groups.map(group => group.instruction ?? ''),
+    allow: [BotActionKind.Delete, BotActionKind.Reply],
+  }))
   await agent.invoke(botAgentHelper.promptOf(update), { action: 'moderate' })
 })
 ```
@@ -36,9 +44,9 @@ export const moderate = botHandler('moderate', async (update, bot) => {
 
 | Export | What it is |
 |---|---|
-| `botAgentPlugin({ update, bot, allow?, instruction? })` | The `AgentPlugin`: the update as context, the actions as tools; alias `BOT_AGENT_PLUGIN` |
-| `botAgentTools({ update, bot, allow? })` | The same tools without the plugin, as an `AgentToolSet` |
-| `botAgentHelper` | `instructionOf(update, extra?)`, `contextOf(update, instruction?)`, `promptOf(update)` |
+| `botAgentPlugin({ update, bot, allow?, ref?, instruction? })` | The `AgentPlugin`: the update and the instructions (`string \| string[]`) as context, the actions as tools; alias `BOT_AGENT_PLUGIN` |
+| `botAgentTools({ update, bot, allow?, ref? })` | The same tools without the plugin, as an `AgentToolSet` |
+| `botAgentHelper` | `instructionOf(instruction?)`, `contextOf(update, instruction?)`, `promptOf(update)` |
 | `BotAgentTool`, `BOT_AGENT_TOOL_ACTIONS`, `BOT_AGENT_ACTIONS`, `BOT_AGENT_DONE`, `BOT_AGENT_ORDER` | Tool names, the action each performs, the default `allow`, the success answer, the plugin order |
 | `BotAgentOptions`, `BotAgentToolsOptions`, `BotAgentHelper` | Types |
 
@@ -55,7 +63,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.59
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 3,
   "package": "@owlmeans/bot-agent",
-  "version": "0.1.18-rc.2",
-  "generatedAt": "2026-10-26T22:23:53.870Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.761Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/bot-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bot-agent
-description: How to use @owlmeans/bot-agent — the bridge that lets an @owlmeans/agent agent act on ONE chat-bot update. botAgentPlugin contributes the message (platform, chat, sender, text, replied-to text) and the matched keyword groups' instructions as context, and the bot's actions (reply, delete, warn, mute, ban, react) as never-throwing tools limited to what the platform supports and allow names; botAgentTools gives the tools without the plugin; botAgentHelper turns an update into instructions, context and the opening turn. Auto-invoked when an AI bot's handler hands a message to an agent, when writing a target's bot agent module, or when importing botAgentPlugin.
+description: How to use @owlmeans/bot-agent — the bridge that lets an @owlmeans/agent agent act on ONE chat-bot update. botAgentPlugin contributes the message (platform, chat, sender, text, replied-to text) and the instructions the handler passes (those of the application's own keyword groups the message matched) as context, and the bot's actions (reply, delete, warn, mute, ban, react) as never-throwing tools limited to what the platform supports and allow names, each recording the handler's ref; botAgentTools gives the tools without the plugin; botAgentHelper turns instructions and an update into instruction text, context and the opening turn. Auto-invoked when an AI bot's handler hands a message to an agent, when writing a target's bot agent module, or when importing botAgentPlugin.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,21 +8,23 @@ user-invocable: false
 # @owlmeans/bot-agent
 
 **Layer:** Server (its tools act through `@owlmeans/server-bot`'s `BotActions`; type-only edge)
-**Install:** `"@owlmeans/bot-agent": "^0.1.18-rc.2"` in `dependencies`, plus the `@owlmeans/agent` and
+**Install:** `"@owlmeans/bot-agent": "^0.1.18"` in `dependencies`, plus the `@owlmeans/agent` and
 `@langchain/core` **peers**
-**Contract:** `@owlmeans/bot` (updates, matches, action kinds); actions: `@owlmeans/server-bot`
+**Contract:** `@owlmeans/bot` (updates, action kinds, the text helper); actions: `@owlmeans/server-bot`
 
 An AI bot's handler receives an update and the connection's `BotActions`. This package turns the two
-into what an agent needs: the update as CONTEXT, the actions as TOOLS. It stores, receives and sends
-nothing itself — every tool calls a `BotActions` method, which records one activity whatever happens.
+into what an agent needs: the update and the instructions as CONTEXT, the actions as TOOLS. It
+stores, receives, matches and sends nothing itself — the handler matches the message against the
+application's own keyword groups and passes their instructions; every tool calls a `BotActions`
+method, which records one activity whatever happens.
 
 ## Key exports
 
 | Export | What it is |
 |---|---|
-| `botAgentPlugin({ update, bot, allow?, instruction? })` → `AgentPlugin` | The update as context, the actions as tools; alias `BOT_AGENT_PLUGIN` (`'bot-agent'`), order `BOT_AGENT_ORDER` (30) |
-| `botAgentTools({ update, bot, allow? })` → `AgentToolSet` | The same tools without the plugin |
-| `botAgentHelper.instructionOf(update, extra?)` | The matched groups' instructions (trimmed, empties and repeats dropped) then `extra`, joined by a blank line; `''` when none |
+| `botAgentPlugin({ update, bot, allow?, ref?, instruction? })` → `AgentPlugin` | The update and the instructions as context, the actions as tools; alias `BOT_AGENT_PLUGIN` (`'bot-agent'`), order `BOT_AGENT_ORDER` (30) |
+| `botAgentTools({ update, bot, allow?, ref? })` → `AgentToolSet` | The same tools without the plugin |
+| `botAgentHelper.instructionOf(instruction?)` | `instruction` (`string \| readonly string[]`) trimmed, empties and repeats dropped, joined by a blank line; `''` when none |
 | `botAgentHelper.contextOf(update, instruction?)` | The context blocks the plugin contributes |
 | `botAgentHelper.promptOf(update)` | The opening turn to `invoke` the agent with |
 | `BotAgentTool` | `reply` · `delete` · `warn` · `mute` · `ban` · `react` — the names the model calls |
@@ -31,17 +33,16 @@ nothing itself — every tool calls a `BotActions` method, which records one act
 
 ## Context
 
-Three markdown blocks, in this order — they land in the agent's project message
+One or two markdown blocks, in this order — they land in the agent's project message
 (`PromptBlock.Context`), never in the cached system prompt ([[llm-prompt-caching]]):
 
 1. `# The chat message` — `Platform:` (the descriptor's title), `Chat:` (kind and title), `Sender:`
    (name and @username, "a bot" when it is one), `Command:` when any, whether it is addressed to the
    bot, the text as a `>` quote marked as data, never instructions, and the replied-to text when any.
    An update without a message says so.
-2. `# Matched keyword groups` — per `update.matches`, highest priority first: name, the keywords that
-   matched, the group's `Action:` (omitted for `agent`), its `Reply text:` and `Instruction:` when
-   set. No match says "None".
-3. `# Instruction` — the `instruction` option, when given.
+2. `# Instruction` — `instructionOf(instruction)`, when it holds any text: the instructions of the
+   application's keyword groups the handler matched (an `ai-bot` group's `instruction` field), in the
+   order passed, optionally followed by one of the product's own. Absent or blank: no block.
 
 ## Tools
 
@@ -55,7 +56,8 @@ Three markdown blocks, in this order — they land in the agent's project messag
 | `ban` | `bot.ban(update)` | — | `ban` allowed + supported, a sender |
 
 - Every tool acts on THE update it was built for — its message, its sender, its chat. The activity it
-  records carries the update id and, as `rule`, the FIRST matched group.
+  records carries the update id and, as `ref`, the `ref` option (the id of the application's keyword
+  group the handler followed; absent when not given).
 - An answer is `done`, or `{ error: <the action's error> }` — `BotActionResult.error`, ONE short
   sentence ("WhatsApp cannot delete messages.", "A mute lasts at least one minute."), never its machine
   `code` — the `toolHelper` contract: the loop turns it into an error tool message the model reads and
@@ -73,24 +75,28 @@ Three markdown blocks, in this order — they land in the agent's project messag
   the platform lacks (WhatsApp: no `delete`, `mute`, `ban`; Slack: `delete` only with `userToken`).
 - **One plugin per update.** The alias is stable: `agent.use(botAgentPlugin(…))` for the next update
   REPLACES the previous one. Build the agent per update; never share a plugin across updates.
-- **The groups' instructions are the guidance.** The agent's persona (its `prompt.role`) says what
-  kind of bot it is; it never restates or overrides what a group instructs.
+- **The groups' instructions are the guidance.** The handler matches the message against the
+  application's own keyword groups (`botTextHelper.matched`) and passes the matched ones'
+  `instruction`s; the agent's persona (its `prompt.role`) says what kind of bot it is and never
+  restates or overrides what a group instructs.
 - **The tool names are generic** (`reply`, `delete`) — do not give the same agent other tools under
   those names: tool sets merge by key.
 - **The agent's failure never escapes the handler.** A ReAct run is not resumable: a throw makes the
   worker retry the update, which re-runs the agent and repeats the actions it already took. Catch it
   and `bot.note` the failure; a missing model key is noted BEFORE the agent is built.
 - **A ONE-answer bot needs no agent.** A support bot that only writes a reply can ask one model call
-  (`makeLlmModel(…).ask`) with `botAgentHelper.instructionOf(update)` and `contextOf(update)`, then
-  `bot.reply` the answer — no tools, no loop.
+  (`makeLlmModel(…).ask`) with `botAgentHelper.contextOf(update, instructions)`, then `bot.reply` the
+  answer with `{ ref }` — no tools, no loop.
 
 ## Target wiring
 
 An `ai-bot` target (docs/bots.md §3.5, §5): the generated agent module
 `sources/backend/src/agents/<alias>.ts` builds the agent from the project's ONE model module
 `lib/llm.ts` (`getModel()`, `llmSpectator`); the generated handler
-`sources/backend/src/bot/handlers/<slug>.ts` checks `llmConfigured` first and `bot.note`s the
-refusal, then `.use(botAgentPlugin({ update, bot }))` and invokes the agent with the update.
+`sources/backend/src/bot/handlers/<slug>.ts` loads the application's keyword groups for
+`update.scope` through the backend model, matches the text with `botTextHelper.matched`, checks
+`llmConfigured` and `bot.note`s the refusal, then `.use(botAgentPlugin({ update, bot, ref, instruction }))`
+and invokes the agent with the update.
 
 ```ts
 // sources/backend/src/agents/moderator.ts
@@ -98,7 +104,7 @@ import { makeAgentModel, type AgentModel } from '@owlmeans/agent'
 import { DEFAULT_EFFORT, makeExecutionService, makePromptService, spectate } from '@owlmeans/llm'
 import { getModel, llmSpectator, ModelUnavailable } from '../lib/llm.js'
 
-/** The persona. What to do with a message comes from the groups it matched, never from here. */
+/** The persona. What to do with a message comes from the instructions of the groups it matched, never from here. */
 const ROLE = 'You moderate a Telegram community for its owner. Judge the member\'s message against the '
   + 'instructions of the keyword groups it matched and act only through your tools: delete what breaks a '
   + 'rule, warn the sender, mute a repeat offender. Never chat with the member.'
@@ -124,31 +130,39 @@ export const makeModeratorAgent = (): AgentModel => makeAgentModel({
 ```ts
 // sources/backend/src/bot/handlers/moderate.ts
 import { compactionHelper } from '@owlmeans/agent'
-import { BotActionKind } from '@owlmeans/bot'
+import { BotActionKind, botTextHelper } from '@owlmeans/bot'
 import { botAgentHelper, botAgentPlugin } from '@owlmeans/bot-agent'
 import { logger } from '@owlmeans/log'
 import { botHandler } from '@owlmeans/server-bot'
 import { makeModeratorAgent } from '../../agents/moderator.js'
 import { llmConfigured, MODEL_UNAVAILABLE } from '../../lib/llm.js'
+import { makeKeywordGroupModel } from '../../models/keyword-group/keyword-group.js'  // the app's own records
 
 const log = logger('bot:moderate')
 
-export const moderate = botHandler('moderate', async (update, bot) => {
-  if (update.matches.length === 0) return            // only what a keyword group matched
+export const moderate = botHandler('moderate', async (update, bot, ctx) => {
+  const text = update.message?.text ?? ''
+  const groups = (await makeKeywordGroupModel(ctx).enabledOf(update.scope))
+    .filter(group => botTextHelper.matched(text, group.keywords).length > 0)
+  if (groups.length === 0) return                    // only what a keyword group matched
+  const ref = groups[0].id                           // recorded on every activity the agent causes
   if (!llmConfigured) {                              // no model key: record the refusal, ask nothing
-    await bot.note(update, MODEL_UNAVAILABLE)
+    await bot.note(update, MODEL_UNAVAILABLE, { ref })
     return
   }
 
   const agent = makeModeratorAgent()
-  agent.use(botAgentPlugin({ update, bot, allow: [BotActionKind.Delete, BotActionKind.Reply, BotActionKind.Mute] }))
+  agent.use(botAgentPlugin({
+    update, bot, ref, instruction: groups.map(group => group.instruction ?? ''),
+    allow: [BotActionKind.Delete, BotActionKind.Reply, BotActionKind.Mute],
+  }))
   try {
     const { message } = await agent.invoke(botAgentHelper.promptOf(update), { action: 'moderate' })
-    await bot.note(update, compactionHelper.messageText(message))   // what the agent did, on the activity
+    await bot.note(update, compactionHelper.messageText(message), { ref })   // what the agent did, on the activity
   } catch (error) {
     // Never rethrow: a retried update re-runs the agent and repeats the actions it already took.
     log.warn('The moderator failed', error)
-    await bot.note(update, 'The moderator could not decide on this message.')
+    await bot.note(update, 'The moderator could not decide on this message.', { ref })
   }
 })
 ```
@@ -165,14 +179,15 @@ export const moderate = botHandler('moderate', async (update, bot) => {
 Category A, `bun test ./tests`: real `@owlmeans/server-bot` with its built-in plugins (static
 resources, mock Telegram and WhatsApp connections, messages simulated and dispatched by the runtime)
 and a scripted model double (`tests/_tools/model.ts`, as in the agent's
-[testing](../agent/parts/testing.md) part) driving the loop. Covered: the context blocks of a
-matched update; the tool set by `supports` / `allow` / the update's shape; each tool's action, update,
-rule and answer; refusals answered as the action's sentence; one alias; a full loop acting through
+[testing](../agent/parts/testing.md) part) driving the loop; the specs' handlers match their own
+keyword lists with `botTextHelper` and pass `ref` and `instruction`, as a generated one does. Covered:
+`instructionOf`; the context blocks (with and without instructions); the tool set by `supports` /
+`allow` / the update's shape; each tool's action, update, `ref` and answer; refusals answered as the action's sentence; one alias; a full loop acting through
 the tools and recovering from a refused or unoffered tool.
 
 ## Depends On
 
-- `@owlmeans/bot` — `BotUpdate`, `BotActionKind`, `BOT_PLATFORMS`
+- `@owlmeans/bot` — `BotUpdate`, `BotActionKind`, `BOT_PLATFORMS` (a handler also uses its `botTextHelper`)
 - `@owlmeans/server-bot` — `BotActions`, `BotActionResult` (types only)
 - peers `@owlmeans/agent` (`AgentPlugin`, `toolHelper`), `@langchain/core` (`tool`)
 
@@ -180,5 +195,5 @@ the tools and recovering from a refused or unoffered tool.
 
 - [[agent]] — the `AgentPlugin` seam, `toolHelper.safeInvokeTool`, `makeAgentModel`
 - [[server-bot]] — handlers, `BotActions` (never throw), the worker runtime
-- [[bot]] — updates, matches, platform support
+- [[bot]] — updates, `botTextHelper`, platform support
 - [[llm]] — `makeExecutionService`, `makePromptService`, `spectate`

package/build/helpers/agent/types.d.ts

@@ -2,17 +2,18 @@ import type { BotUpdate } from '@owlmeans/bot';
 /** Turning a bot update into what an agent — or a single model call — is told. Pure; never throws. */
 export interface BotAgentHelper {
     /**
-     * The matched groups' instructions, in match order — trimmed, empties and repeats dropped — then
-     * `extra`; joined by a blank line. `''` when there is none. For a caller that asks ONE model call
-     * (no tools) and needs the owner's guidance as a single text.
+     * The instruction text: one instruction, or several (the instructions of the application's
+     * keyword groups the message matched, in the order the handler passes them) — each trimmed,
+     * empties and repeats dropped, joined by a blank line. `''` when there is none. For a caller that
+     * asks ONE model call (no tools) and needs the owner's guidance as a single text.
      */
-    instructionOf: (update: BotUpdate, extra?: string) => string;
+    instructionOf: (instruction?: string | readonly string[]) => string;
     /**
      * The context `botAgentPlugin` contributes, one markdown block each: the message (platform, chat,
-     * sender, text quoted as data, the replied-to text), the matched keyword groups (name, matched
-     * keywords, action, fixed reply, instruction) and, when given, `instruction`.
+     * sender, text quoted as data, the replied-to text) and, when `instruction` holds any text, the
+     * instruction block (`# Instruction`, `instructionOf(instruction)`).
      */
-    contextOf: (update: BotUpdate, instruction?: string) => string[];
+    contextOf: (update: BotUpdate, instruction?: string | readonly string[]) => string[];
     /** The opening turn to invoke the agent with: act on the message as the context instructs, through the tools. */
     promptOf: (update: BotUpdate) => string;
 }

package/build/helpers/agent/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/helpers/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5D;;;;OAIG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAA;IAChE,iHAAiH;IACjH,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAA;CACxC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/helpers/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,aAAa,EAAE,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,KAAK,MAAM,CAAA;IACnE;;;;OAIG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACpF,iHAAiH;IACjH,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAA;CACxC"}

package/build/helpers/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/helpers/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,eAAO,MAAM,oBAAoB,QAAO,cA2HvC,CAAA;AAED,eAAO,MAAM,cAAc,gBAAyB,CAAA"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/helpers/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,eAAO,MAAM,oBAAoB,QAAO,cA8FvC,CAAA;AAED,eAAO,MAAM,cAAc,gBAAyB,CAAA"}

package/build/helpers/agent.js

@@ -1,4 +1,4 @@
-import { BOT_PLATFORMS, BotRuleAction, BotUpdateKind } from '@owlmeans/bot';
+import { BOT_PLATFORMS, BotUpdateKind } from '@owlmeans/bot';
 import { BOT_AGENT_DONE } from '../consts.js';
 export const createBotAgentHelper = () => {
     /** A person's words as a quote block — read as data, never as headings or instructions. */
@@ -17,10 +17,12 @@ export const createBotAgentHelper = () => {
         const title = update.chat.title?.trim() ?? '';
         return title !== '' ? `${update.chat.kind} "${title}"` : update.chat.kind;
     };
-    const instructionOf = (update, extra) => {
+    const instructionOf = instruction => {
+        const list = typeof instruction === 'string' ? [instruction]
+            : Array.isArray(instruction) ? instruction : [];
         const seen = new Set();
         const parts = [];
-        for (const text of [...(update.matches ?? []).map(match => match.rule.instruction), extra]) {
+        for (const text of list) {
             const trimmed = typeof text === 'string' ? text.trim() : '';
             if (trimmed !== '' && !seen.has(trimmed)) {
                 seen.add(trimmed);
@@ -54,38 +56,11 @@ export const createBotAgentHelper = () => {
         }
         return lines.join('\n');
     };
-    const groupsBlock = (update) => {
-        const matches = update.matches ?? [];
-        if (matches.length === 0) {
-            return '# Matched keyword groups\n\nNone — the message matched no keyword group of the bot\'s owner.';
-        }
-        const groups = matches.map(({ rule, keywords }, index) => {
-            const lines = [`## ${index + 1}. ${rule.name}`, `Keywords matched: ${keywords.join(', ')}`];
-            if (rule.action !== BotRuleAction.Agent) {
-                lines.push(`Action: ${rule.action}`);
-            }
-            if (typeof rule.reply === 'string' && rule.reply.trim() !== '') {
-                lines.push(`Reply text: ${rule.reply.trim()}`);
-            }
-            if (typeof rule.instruction === 'string' && rule.instruction.trim() !== '') {
-                lines.push(`Instruction: ${rule.instruction.trim()}`);
-            }
-            return lines.join('\n');
-        });
-        return [
-            '# Matched keyword groups',
-            '',
-            'The message matched these keyword groups of the bot\'s owner, highest priority first. '
-                + 'Follow their instructions.',
-            '',
-            groups.join('\n\n'),
-        ].join('\n');
-    };
     const contextOf = (update, instruction) => {
-        const blocks = [messageBlock(update), groupsBlock(update)];
-        const extra = typeof instruction === 'string' ? instruction.trim() : '';
-        if (extra !== '') {
-            blocks.push(`# Instruction\n\n${extra}`);
+        const blocks = [messageBlock(update)];
+        const text = instructionOf(instruction);
+        if (text !== '') {
+            blocks.push(`# Instruction\n\n${text}`);
         }
         return blocks;
     };

package/build/helpers/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/helpers/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/helpers/agent.ts"],"names":[],"mappings":"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"}

package/build/plugin.d.ts

@@ -4,8 +4,9 @@ import type { BotAgentOptions } from './types.js';
  * Lets an `@owlmeans/agent` agent act on ONE chat-bot update.
  *
  * `context` contributes the message — platform, chat, sender, the text quoted as data, the replied-to
- * text — the matched keyword groups with their instructions, and `instruction` when given; it lands
- * in the agent's project message (`PromptBlock.Context`), never in the cached system prompt.
+ * text — and, when given, the instruction block: the instructions of the application's keyword groups
+ * the handler matched (`instruction`). It lands in the agent's project message (`PromptBlock.Context`),
+ * never in the cached system prompt.
  * `tools` are `botAgentTools(options)`: `reply`, `delete`, `warn`, `mute`, `ban`, `react` — only
  * those the platform supports and `allow` names — each acting on the update and never throwing.
  *

package/build/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,YAAa,eAAe,KAAG,WAKxD,CAAA"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,YAAa,eAAe,KAAG,WAKxD,CAAA"}

package/build/plugin.js

@@ -5,8 +5,9 @@ import { botAgentTools } from './tools.js';
  * Lets an `@owlmeans/agent` agent act on ONE chat-bot update.
  *
  * `context` contributes the message — platform, chat, sender, the text quoted as data, the replied-to
- * text — the matched keyword groups with their instructions, and `instruction` when given; it lands
- * in the agent's project message (`PromptBlock.Context`), never in the cached system prompt.
+ * text — and, when given, the instruction block: the instructions of the application's keyword groups
+ * the handler matched (`instruction`). It lands in the agent's project message (`PromptBlock.Context`),
+ * never in the cached system prompt.
  * `tools` are `botAgentTools(options)`: `reply`, `delete`, `warn`, `mute`, `ban`, `react` — only
  * those the platform supports and `allow` names — each acting on the update and never throwing.
  *

package/build/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAwB,EAAe,EAAE,CAAC,CAAC;IACxE,KAAK,EAAE,gBAAgB;IACvB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC;IAClF,KAAK,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC;CACpC,CAAC,CAAA"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAwB,EAAe,EAAE,CAAC,CAAC;IACxE,KAAK,EAAE,gBAAgB;IACvB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC;IAClF,KAAK,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC;CACpC,CAAC,CAAA"}

package/build/tools.d.ts

@@ -8,7 +8,8 @@ import type { BotAgentToolsOptions } from './types.js';
  * update has what it acts on (a message for `reply` / `warn` / `delete` / `react`, a sender for
  * `mute` / `ban`). Every tool NEVER throws: it answers `done`, or `{ error }` with the action's
  * one-sentence `error` — the `toolHelper` contract, so a refused action is something the model reads
- * and adapts to. The activity each action records names the first matched group as its rule.
+ * and adapts to. Every action records `ref` (when given) on its activity — the application's own
+ * record the handler followed.
  */
 export declare const botAgentTools: (options: BotAgentToolsOptions) => AgentToolSet;
 //# sourceMappingURL=tools.d.ts.map

package/build/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,YAAY,EAA0B,MAAM,iBAAiB,CAAA;AAKvF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAOtD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,YAAa,oBAAoB,KAAG,YAqE7D,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,YAAY,EAA0B,MAAM,iBAAiB,CAAA;AAKvF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAOtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,YAAa,oBAAoB,KAAG,YAoE7D,CAAA"}

package/build/tools.js

@@ -12,13 +12,13 @@ import { BotAgentMuteSchema, BotAgentNoArgsSchema, BotAgentReactSchema, BotAgent
  * update has what it acts on (a message for `reply` / `warn` / `delete` / `react`, a sender for
  * `mute` / `ban`). Every tool NEVER throws: it answers `done`, or `{ error }` with the action's
  * one-sentence `error` — the `toolHelper` contract, so a refused action is something the model reads
- * and adapts to. The activity each action records names the first matched group as its rule.
+ * and adapts to. Every action records `ref` (when given) on its activity — the application's own
+ * record the handler followed.
  */
 export const botAgentTools = (options) => {
     const { update, bot } = options;
     const allowed = new Set(options.allow ?? BOT_AGENT_ACTIONS);
-    const rule = update.matches?.[0]?.rule.id;
-    const opts = rule != null ? { rule } : {};
+    const opts = options.ref != null && options.ref !== '' ? { ref: options.ref } : {};
     const supported = (kind) => {
         try {
             return bot.supports(kind);

package/build/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -13,9 +13,18 @@ export interface BotAgentToolsOptions {
      * with `bot.supports(kind)`: a tool the platform cannot perform is never offered.
      */
     allow?: readonly BotActionKind[];
+    /**
+     * An opaque reference every action records on its activity (`{ ref }`) — the id of the
+     * application's own record the handler followed (the keyword group the message matched).
+     */
+    ref?: string;
 }
 export interface BotAgentOptions extends BotAgentToolsOptions {
-    /** One more instruction, contributed after the matched groups' — the product's own rule for this agent. */
-    instruction?: string;
+    /**
+     * What the model is told for this message: the instructions of the application's keyword groups
+     * the message matched (the handler matches them and passes them here), or one instruction of the
+     * product's own. Absent or blank: the context is the message alone.
+     */
+    instruction?: string | readonly string[];
 }
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,MAAM,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,GAAG,EAAE,UAAU,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CACjC;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D,2GAA2G;IAC3G,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,MAAM,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,GAAG,EAAE,UAAU,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;CACzC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@owlmeans/bot-agent",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18",
   "license": "MIT",
-  "description": "The bridge between an OwlMeans chat bot and an @owlmeans/agent agent — botAgentPlugin contributes a bot update (platform, chat, sender, message, the matched keyword groups and their instructions) as the agent's context and the bot's actions (reply, delete, warn, mute, ban, react) as never-throwing tools, limited to what the platform supports and the caller allows.",
+  "description": "The bridge between an OwlMeans chat bot and an @owlmeans/agent agent \u2014 botAgentPlugin contributes a bot update (platform, chat, sender, message) and the instructions its handler passes as the agent's context and the bot's actions (reply, delete, warn, mute, ban, react) as never-throwing tools, limited to what the platform supports and the caller allows.",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
@@ -23,24 +23,24 @@
     }
   },
   "dependencies": {
-    "@owlmeans/bot": "^0.1.18-rc.2",
-    "@owlmeans/server-bot": "^0.1.18-rc.2"
+    "@owlmeans/bot": "^0.1.18",
+    "@owlmeans/server-bot": "^0.1.18"
   },
   "peerDependencies": {
     "@langchain/core": "^1.2.14",
-    "@owlmeans/agent": "^0.1.18-rc.56"
+    "@owlmeans/agent": "^0.1.18"
   },
   "devDependencies": {
     "@langchain/core": "^1.2.14",
     "@langchain/langgraph": "^1.4.19",
     "@langchain/langgraph-checkpoint": "^1.1.5",
-    "@owlmeans/agent": "^0.1.18-rc.56",
-    "@owlmeans/context": "^0.1.18-rc.35",
-    "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/llm": "^0.1.18-rc.54",
-    "@owlmeans/llm-common": "^0.1.18-rc.40",
-    "@owlmeans/log": "^0.1.18-rc.4",
-    "@owlmeans/static-resource": "^0.1.18-rc.40",
+    "@owlmeans/agent": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@owlmeans/llm": "^0.1.18",
+    "@owlmeans/llm-common": "^0.1.18",
+    "@owlmeans/log": "^0.1.18",
+    "@owlmeans/static-resource": "^0.1.18",
     "@types/bun": "^1.4.2",
     "@types/node": "^26.6.4",
     "ajv": "^8.20.0",

package/src/helpers/agent/types.ts

@@ -3,17 +3,18 @@ import type { BotUpdate } from '@owlmeans/bot'
 /** Turning a bot update into what an agent — or a single model call — is told. Pure; never throws. */
 export interface BotAgentHelper {
   /**
-   * The matched groups' instructions, in match order — trimmed, empties and repeats dropped — then
-   * `extra`; joined by a blank line. `''` when there is none. For a caller that asks ONE model call
-   * (no tools) and needs the owner's guidance as a single text.
+   * The instruction text: one instruction, or several (the instructions of the application's
+   * keyword groups the message matched, in the order the handler passes them) — each trimmed,
+   * empties and repeats dropped, joined by a blank line. `''` when there is none. For a caller that
+   * asks ONE model call (no tools) and needs the owner's guidance as a single text.
    */
-  instructionOf: (update: BotUpdate, extra?: string) => string
+  instructionOf: (instruction?: string | readonly string[]) => string
   /**
    * The context `botAgentPlugin` contributes, one markdown block each: the message (platform, chat,
-   * sender, text quoted as data, the replied-to text), the matched keyword groups (name, matched
-   * keywords, action, fixed reply, instruction) and, when given, `instruction`.
+   * sender, text quoted as data, the replied-to text) and, when `instruction` holds any text, the
+   * instruction block (`# Instruction`, `instructionOf(instruction)`).
    */
-  contextOf: (update: BotUpdate, instruction?: string) => string[]
+  contextOf: (update: BotUpdate, instruction?: string | readonly string[]) => string[]
   /** The opening turn to invoke the agent with: act on the message as the context instructs, through the tools. */
   promptOf: (update: BotUpdate) => string
 }

package/src/helpers/agent.ts

@@ -1,4 +1,4 @@
-import { BOT_PLATFORMS, BotRuleAction, BotUpdateKind, type BotSenderRef, type BotUpdate } from '@owlmeans/bot'
+import { BOT_PLATFORMS, BotUpdateKind, type BotSenderRef, type BotUpdate } from '@owlmeans/bot'
 import { BOT_AGENT_DONE } from '../consts.js'
 import type { BotAgentHelper } from './agent/types.js'
 
@@ -24,10 +24,12 @@ export const createBotAgentHelper = (): BotAgentHelper => {
     return title !== '' ? `${update.chat.kind} "${title}"` : update.chat.kind
   }
 
-  const instructionOf: BotAgentHelper['instructionOf'] = (update, extra) => {
+  const instructionOf: BotAgentHelper['instructionOf'] = instruction => {
+    const list: readonly unknown[] = typeof instruction === 'string' ? [instruction]
+      : Array.isArray(instruction) ? instruction : []
     const seen = new Set<string>()
     const parts: string[] = []
-    for (const text of [...(update.matches ?? []).map(match => match.rule.instruction), extra]) {
+    for (const text of list) {
       const trimmed = typeof text === 'string' ? text.trim() : ''
       if (trimmed !== '' && !seen.has(trimmed)) {
         seen.add(trimmed)
@@ -75,42 +77,11 @@ export const createBotAgentHelper = (): BotAgentHelper => {
     return lines.join('\n')
   }
 
-  const groupsBlock = (update: BotUpdate): string => {
-    const matches = update.matches ?? []
-    if (matches.length === 0) {
-      return '# Matched keyword groups\n\nNone — the message matched no keyword group of the bot\'s owner.'
-    }
-
-    const groups = matches.map(({ rule, keywords }, index) => {
-      const lines = [`## ${index + 1}. ${rule.name}`, `Keywords matched: ${keywords.join(', ')}`]
-      if (rule.action !== BotRuleAction.Agent) {
-        lines.push(`Action: ${rule.action}`)
-      }
-      if (typeof rule.reply === 'string' && rule.reply.trim() !== '') {
-        lines.push(`Reply text: ${rule.reply.trim()}`)
-      }
-      if (typeof rule.instruction === 'string' && rule.instruction.trim() !== '') {
-        lines.push(`Instruction: ${rule.instruction.trim()}`)
-      }
-
-      return lines.join('\n')
-    })
-
-    return [
-      '# Matched keyword groups',
-      '',
-      'The message matched these keyword groups of the bot\'s owner, highest priority first. '
-      + 'Follow their instructions.',
-      '',
-      groups.join('\n\n'),
-    ].join('\n')
-  }
-
   const contextOf: BotAgentHelper['contextOf'] = (update, instruction) => {
-    const blocks = [messageBlock(update), groupsBlock(update)]
-    const extra = typeof instruction === 'string' ? instruction.trim() : ''
-    if (extra !== '') {
-      blocks.push(`# Instruction\n\n${extra}`)
+    const blocks = [messageBlock(update)]
+    const text = instructionOf(instruction)
+    if (text !== '') {
+      blocks.push(`# Instruction\n\n${text}`)
     }
 
     return blocks

package/src/plugin.ts

@@ -8,8 +8,9 @@ import type { BotAgentOptions } from './types.js'
  * Lets an `@owlmeans/agent` agent act on ONE chat-bot update.
  *
  * `context` contributes the message — platform, chat, sender, the text quoted as data, the replied-to
- * text — the matched keyword groups with their instructions, and `instruction` when given; it lands
- * in the agent's project message (`PromptBlock.Context`), never in the cached system prompt.
+ * text — and, when given, the instruction block: the instructions of the application's keyword groups
+ * the handler matched (`instruction`). It lands in the agent's project message (`PromptBlock.Context`),
+ * never in the cached system prompt.
  * `tools` are `botAgentTools(options)`: `reply`, `delete`, `warn`, `mute`, `ban`, `react` — only
  * those the platform supports and `allow` names — each acting on the update and never throwing.
  *

package/src/tools.ts

@@ -20,13 +20,13 @@ import type { BotAgentToolArgs } from './tools/types.local.js'
  * update has what it acts on (a message for `reply` / `warn` / `delete` / `react`, a sender for
  * `mute` / `ban`). Every tool NEVER throws: it answers `done`, or `{ error }` with the action's
  * one-sentence `error` — the `toolHelper` contract, so a refused action is something the model reads
- * and adapts to. The activity each action records names the first matched group as its rule.
+ * and adapts to. Every action records `ref` (when given) on its activity — the application's own
+ * record the handler followed.
  */
 export const botAgentTools = (options: BotAgentToolsOptions): AgentToolSet => {
   const { update, bot } = options
   const allowed = new Set<BotActionKind>(options.allow ?? BOT_AGENT_ACTIONS)
-  const rule = update.matches?.[0]?.rule.id
-  const opts: BotActionOptions = rule != null ? { rule } : {}
+  const opts: BotActionOptions = options.ref != null && options.ref !== '' ? { ref: options.ref } : {}
 
   const supported = (kind: BotActionKind): boolean => {
     try {

package/src/types.ts

@@ -14,9 +14,18 @@ export interface BotAgentToolsOptions {
    * with `bot.supports(kind)`: a tool the platform cannot perform is never offered.
    */
   allow?: readonly BotActionKind[]
+  /**
+   * An opaque reference every action records on its activity (`{ ref }`) — the id of the
+   * application's own record the handler followed (the keyword group the message matched).
+   */
+  ref?: string
 }
 
 export interface BotAgentOptions extends BotAgentToolsOptions {
-  /** One more instruction, contributed after the matched groups' — the product's own rule for this agent. */
-  instruction?: string
+  /**
+   * What the model is told for this message: the instructions of the application's keyword groups
+   * the message matched (the handler matches them and passes them here), or one instruction of the
+   * product's own. Absent or blank: the context is the message alone.
+   */
+  instruction?: string | readonly string[]
 }

package/tests/context.ts

@@ -1,11 +1,10 @@
 import { randomUUID } from 'node:crypto'
 import { AppType, makeBasicContext, type BasicConfig, type BasicContext } from '@owlmeans/context'
-import { BotPlatform, BotTransport, type BotRuleInput, type BotSimulateInput, type BotUpdate } from '@owlmeans/bot'
+import { BotPlatform, BotTransport, botTextHelper, type BotSimulateInput, type BotUpdate } from '@owlmeans/bot'
 import { configureLog } from '@owlmeans/log'
 import {
-  appendBot, botHandler, RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE, type BotActions,
-  type BotActivityRecord, type BotConnectionRecord, type BotHandle, type BotRuleRecord, type BotService,
-  type BotUpdateRecord,
+  appendBot, botHandler, RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_UPDATE, type BotActions,
+  type BotActivityRecord, type BotConnectionRecord, type BotHandle, type BotService, type BotUpdateRecord,
 } from '@owlmeans/server-bot'
 import { createStaticResource } from '@owlmeans/static-resource'
 
@@ -21,14 +20,13 @@ export interface TestBot {
 let stores = 0
 
 /**
- * One real context per test: the four bot resources as `@owlmeans/static-resource` stores (a fresh
+ * One real context per test: the three bot resources as `@owlmeans/static-resource` stores (a fresh
  * key each time), then `appendBot` — what a target's backend does with its Postgres resources.
  */
 export const makeTestBot = (): TestBot => {
   const key = `bot-agent-tests-${++stores}`
   const context = makeBasicContext<BasicConfig>({ ready: false, service: 'bot-agent-tests', type: AppType.Backend, services: {} })
   context.registerResource(createStaticResource<BotConnectionRecord>(RES_BOT_CONNECTION, `${key}-connection`))
-  context.registerResource(createStaticResource<BotRuleRecord>(RES_BOT_RULE, `${key}-rule`))
   context.registerResource(createStaticResource<BotUpdateRecord>(RES_BOT_UPDATE, `${key}-update`))
   context.registerResource(createStaticResource<BotActivityRecord>(RES_BOT_ACTIVITY, `${key}-activity`))
   const service = appendBot(context, { secret: () => 'bot-agent-tests-secret' })
@@ -49,19 +47,14 @@ export interface Received {
 }
 
 /**
- * A message through the platform's own path (Telegram unless `platform` says otherwise): the rules
- * saved, the message simulated on a mock connection and dispatched by the worker's runtime to
- * `handle` — the update and the actions a handler receives. `handle` runs inside the handler, as a
- * target's would.
+ * A message through the platform's own path (Telegram unless `platform` says otherwise): simulated on
+ * a mock connection and dispatched by the worker's runtime to `handle` — the update and the actions a
+ * handler receives. `handle` runs inside the handler, as a target's would.
  */
 export const receive = async (
-  bot: TestBot, input: BotSimulateInput, rules: BotRuleInput[] = [], handle?: BotHandle,
-  platform: BotPlatform = BotPlatform.Telegram,
+  bot: TestBot, input: BotSimulateInput, handle?: BotHandle, platform: BotPlatform = BotPlatform.Telegram,
 ): Promise<Received> => {
   const connection = await connect(bot, platform)
-  for (const rule of rules) {
-    await bot.service.rules.save(bot.scope, rule)
-  }
   let received: Received | null = null
   const runtime = bot.service.runtime([botHandler('agent', async (update, actions, context) => {
     received = { connection, update, actions }
@@ -82,4 +75,15 @@ export const receive = async (
  * a platform that can reply, send and react, never delete, mute or ban.
  */
 export const whatsAppUpdate = async (bot: TestBot): Promise<Received> =>
-  await receive(bot, { text: 'When do you open?', sender: { id: '4915550001', name: 'Ann' } }, [], undefined, BotPlatform.WhatsApp)
+  await receive(bot, { text: 'When do you open?', sender: { id: '4915550001', name: 'Ann' } }, undefined, BotPlatform.WhatsApp)
+
+/** An application's own keyword group, as a generated handler reads it from the app's records. */
+export interface KeywordGroup {
+  id: string
+  keywords: string[]
+  instruction?: string
+}
+
+/** What a generated handler does with its groups: the ones the text matches, in the given order. */
+export const matchedGroups = (text: string, groups: readonly KeywordGroup[]): KeywordGroup[] =>
+  groups.filter(group => botTextHelper.matched(text, group.keywords).length > 0)

package/tests/helper.spec.ts

@@ -1,31 +1,29 @@
 import { describe, expect, test } from 'bun:test'
-import { BotChatKind, BotRuleAction } from '@owlmeans/bot'
+import { BotChatKind } from '@owlmeans/bot'
 import { botAgentHelper } from '../src/index.js'
 import { makeTestBot, receive } from './context.js'
 
 describe('@owlmeans/bot-agent — botAgentHelper', () => {
-  test('instructionOf joins the matched groups\' instructions, then the extra one', async () => {
-    const bot = makeTestBot()
-    const { update } = await receive(bot, { text: 'casino idiot rain' }, [
-      { name: 'Spam', keywords: ['casino'], action: BotRuleAction.Agent, instruction: ' Delete advertising. ', order: 1 },
-      { name: 'Rude', keywords: ['idiot'], action: BotRuleAction.Agent, instruction: 'Delete advertising.', order: 2 },
-      { name: 'Weather', keywords: ['rain'], action: BotRuleAction.Reply, reply: 'Umbrella.', order: 3 },
-    ])
-
-    expect(botAgentHelper.instructionOf(update, 'Answer in English.')).toBe('Delete advertising.\n\nAnswer in English.')
-    expect(botAgentHelper.instructionOf({ ...update, matches: [] })).toBe('')
+  test('instructionOf joins the given instructions — trimmed, empties and repeats dropped', () => {
+    expect(botAgentHelper.instructionOf([' Delete advertising. ', 'Delete advertising.', '  ', 'Answer in English.']))
+      .toBe('Delete advertising.\n\nAnswer in English.')
+    expect(botAgentHelper.instructionOf('  Be brief. ')).toBe('Be brief.')
+    expect(botAgentHelper.instructionOf('  ')).toBe('')
+    expect(botAgentHelper.instructionOf([])).toBe('')
+    expect(botAgentHelper.instructionOf()).toBe('')
   })
 
-  test('contextOf says what is absent rather than inventing it', async () => {
+  test('contextOf says what is absent rather than inventing it, and adds no empty instruction block', async () => {
     const bot = makeTestBot()
     const { update } = await receive(bot, { text: 'hi there', chat: { kind: BotChatKind.Private } })
 
     const blocks = botAgentHelper.contextOf({ ...update, sender: undefined, message: undefined }, '  ')
-    expect(blocks).toHaveLength(2)
+    expect(blocks).toHaveLength(1)
     expect(blocks[0]).toContain('Chat: private')
     expect(blocks[0]).not.toContain('Sender:')
     expect(blocks[0]).toContain('The update carries no message.')
-    expect(blocks[1]).toContain('None — the message matched no keyword group')
+    expect(blocks[0]).not.toContain('keyword')
+    expect(botAgentHelper.contextOf(update, ['Greet back.', 'Be brief.'])[1]).toBe('# Instruction\n\nGreet back.\n\nBe brief.')
   })
 
   test('promptOf names the platform and the chat, and the tools\' answers', async () => {

package/tests/loop.spec.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from 'bun:test'
 import type { ToolMessage } from '@langchain/core/messages'
 import { makeAgentModel, type AgentModel, type AgentResult } from '@owlmeans/agent'
-import { BotActionKind, BotRuleAction } from '@owlmeans/bot'
+import { BotActionKind } from '@owlmeans/bot'
 import { DEFAULT_EFFORT, makeExecutionService, makePromptService } from '@owlmeans/llm'
 import { BOT_AGENT_DONE, BotAgentTool, botAgentHelper, botAgentPlugin } from '../src/index.js'
-import { makeTestBot, receive } from './context.js'
+import { makeTestBot, matchedGroups, receive, type KeywordGroup } from './context.js'
 import { scriptedModel, type ScriptedModel, type ScriptedTurn } from './_tools/model.js'
 
 const ROLE = 'You moderate a community chat for its owner. Judge each message against the matched '
@@ -24,8 +24,9 @@ const exec = executions.root({
 const makeModeratorAgent = (scripted: ScriptedModel): AgentModel =>
   makeAgentModel({ exec, agentModel: scripted.model, tools: {}, maxTurns: 6 })
 
-const RULES = [
-  { name: 'Spam', keywords: ['casino'], action: BotRuleAction.Delete, instruction: 'Delete advertising and warn the sender.', order: 1 },
+/** The application's own keyword groups, as its generated handler reads them. */
+const GROUPS: KeywordGroup[] = [
+  { id: 'group-spam', keywords: ['casino'], instruction: 'Delete advertising and warn the sender.' },
 ]
 
 /** A message simulated on a mock Telegram connection; the handler runs the agent over it. */
@@ -33,10 +34,16 @@ const moderate = async (text: string, script: ScriptedTurn[]) => {
   const bot = makeTestBot()
   const scripted = scriptedModel(script)
   let result: AgentResult | null = null
-  const received = await receive(bot, { text, sender: { id: '777', name: 'Spammer' } }, RULES, async (update, actions) => {
+  const received = await receive(bot, { text, sender: { id: '777', name: 'Spammer' } }, async (update, actions) => {
+    // The generated handler: match the app's groups, hand their instructions and the first one's id over.
+    const matched = matchedGroups(update.message?.text ?? '', GROUPS)
+    if (matched.length === 0) {
+      return
+    }
     const agent = makeModeratorAgent(scripted)
     agent.use(botAgentPlugin({
       update, bot: actions, allow: [BotActionKind.Delete, BotActionKind.Reply, BotActionKind.Mute],
+      ref: matched[0].id, instruction: matched.map(group => group.instruction ?? ''),
     }))
     result = await agent.invoke(botAgentHelper.promptOf(update), { action: 'moderate' })
   })
@@ -72,16 +79,15 @@ describe('@owlmeans/bot-agent — an agent loop over a bot update', () => {
     expect(JSON.stringify(system.content)).not.toContain('Best casino in town')
     expect(project.getType()).toBe('human')
     expect(JSON.stringify(project.content)).toContain('> Best casino in town')
-    expect(JSON.stringify(project.content)).toContain('Instruction: Delete advertising and warn the sender.')
+    expect(JSON.stringify(project.content)).toContain('# Instruction\\n\\nDelete advertising and warn the sender.')
 
     expect(tools.map(message => [message.name, message.content, message.status]))
       .toEqual([[BotAgentTool.Delete, BOT_AGENT_DONE, 'success'], [BotAgentTool.Warn, BOT_AGENT_DONE, 'success']])
     expect(result.message.content).toBe('Deleted the casino ad and warned the sender.')
-    const rule = received.update.matches[0].rule.id
     const activity = (await bot.service.activity.list(bot.scope)).reverse()
-    expect(activity.map(entry => [entry.action, entry.ok, entry.update, entry.rule, entry.text ?? null])).toEqual([
-      [BotActionKind.Delete, true, received.update.id, rule, null],
-      [BotActionKind.Reply, true, received.update.id, rule, 'Advertising is not allowed here.'],
+    expect(activity.map(entry => [entry.action, entry.ok, entry.update, entry.ref, entry.text ?? null])).toEqual([
+      [BotActionKind.Delete, true, received.update.id, 'group-spam', null],
+      [BotActionKind.Reply, true, received.update.id, 'group-spam', 'Advertising is not allowed here.'],
     ])
   })
 

package/tests/plugin.spec.ts

@@ -1,32 +1,37 @@
 import { describe, expect, test } from 'bun:test'
 import { makeAgentModel, type AgentRun } from '@owlmeans/agent'
-import { BotActionKind, BotRuleAction } from '@owlmeans/bot'
+import { BotActionKind } from '@owlmeans/bot'
 import { DEFAULT_EFFORT, makeExecutionService, makePromptService } from '@owlmeans/llm'
 import { BOT_AGENT_PLUGIN, BotAgentTool, botAgentPlugin } from '../src/index.js'
-import { makeTestBot, receive, whatsAppUpdate } from './context.js'
+import { makeTestBot, matchedGroups, receive, whatsAppUpdate, type KeywordGroup } from './context.js'
 import { scriptedModel } from './_tools/model.js'
 
-const RULES = [
-  { name: 'Spam', keywords: ['casino', 'free money'], action: BotRuleAction.Delete, instruction: 'Delete advertising.', order: 1 },
-  { name: 'Rudeness', keywords: ['idiot'], action: BotRuleAction.Agent, instruction: 'Warn politely.', reply: 'Be kind.', order: 2 },
-  { name: 'Weather', keywords: ['rain'], action: BotRuleAction.Reply, reply: 'Take an umbrella.', order: 3 },
+/** The application's own keyword groups — the handler matches them, the plugin only hears their instructions. */
+const GROUPS: KeywordGroup[] = [
+  { id: 'g-spam', keywords: ['casino', 'free money'], instruction: 'Delete advertising.' },
+  { id: 'g-rude', keywords: ['idiot'], instruction: 'Warn politely.' },
+  { id: 'g-weather', keywords: ['rain'], instruction: 'Mention the umbrella.' },
 ]
 
 /** The plugin ignores the run it is handed; a spec has none outside a loop. */
 const NO_RUN = {} as AgentRun
 
 describe('@owlmeans/bot-agent — botAgentPlugin', () => {
-  test('contributes the message, chat, sender, replied-to text, every matched group and the instruction', async () => {
+  test('contributes the message, chat, sender, replied-to text and the instructions the handler passes', async () => {
     const bot = makeTestBot()
     const { update, actions } = await receive(bot, {
       text: 'Free money at the CASINO, idiot!\nJoin now',
       chat: { title: 'Gamers' },
       sender: { id: '777', name: 'Spammer', username: 'spammer' },
       replyTo: { id: '5', text: 'Welcome, everyone' },
-    }, RULES)
+    })
 
-    const plugin = botAgentPlugin({ update, bot: actions, instruction: 'Never ban anybody.' })
-    const [message, groups, instruction, ...rest] = await plugin.context!(NO_RUN)
+    const matched = matchedGroups(update.message?.text ?? '', GROUPS)
+    const plugin = botAgentPlugin({
+      update, bot: actions, ref: matched[0].id,
+      instruction: [...matched.map(group => group.instruction ?? ''), 'Never ban anybody.'],
+    })
+    const [message, instruction, ...rest] = await plugin.context!(NO_RUN)
 
     expect(rest).toEqual([])
     expect(message).toContain('Platform: Telegram')
@@ -34,16 +39,15 @@ describe('@owlmeans/bot-agent — botAgentPlugin', () => {
     expect(message).toContain('Sender: Spammer (@spammer)')
     expect(message).toContain('> Free money at the CASINO, idiot!\n> Join now')
     expect(message).toContain('> Welcome, everyone')
-    expect(groups).toContain('## 1. Spam\nKeywords matched: casino, free money\nAction: delete\nInstruction: Delete advertising.')
-    // `agent` is the hand-over itself, not an action to tell the model about.
-    expect(groups).toContain('## 2. Rudeness\nKeywords matched: idiot\nReply text: Be kind.\nInstruction: Warn politely.')
-    expect(groups).not.toContain('Weather')
-    expect(instruction).toBe('# Instruction\n\nNever ban anybody.')
+    expect(instruction).toBe('# Instruction\n\nDelete advertising.\n\nWarn politely.\n\nNever ban anybody.')
+    expect(instruction).not.toContain('umbrella')
+    // No instruction: the message alone.
+    expect(await botAgentPlugin({ update, bot: actions }).context!(NO_RUN)).toEqual([message])
   })
 
   test('offers only the tools the platform supports and allow names', async () => {
     const bot = makeTestBot()
-    const telegram = await receive(bot, { text: 'casino' }, RULES)
+    const telegram = await receive(bot, { text: 'casino' })
     const whatsApp = await whatsAppUpdate(bot)
     const names = (options: Parameters<typeof botAgentPlugin>[0]): string[] =>
       Object.values(botAgentPlugin(options).tools!(NO_RUN)).map(item => item.name)

package/tests/tools.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import { toolHelper } from '@owlmeans/agent'
-import { BotActionKind, BotRuleAction, BotTransport } from '@owlmeans/bot'
+import { BotActionKind, BotTransport } from '@owlmeans/bot'
 import { telegramBotPlatform } from '@owlmeans/server-bot'
 import { BOT_AGENT_DONE, BotAgentTool, botAgentTools } from '../src/index.js'
 import { makeTestBot, receive } from './context.js'
@@ -9,12 +9,12 @@ const callOf = (name: string, args: Record<string, unknown> = {}) =>
   ({ name, args, id: `call_${name}`, type: 'tool_call' as const })
 
 describe('@owlmeans/bot-agent — botAgentTools', () => {
-  test('each tool performs its action on the update and answers done', async () => {
+  test('each tool performs its action on the update, records the ref, and answers done', async () => {
     const bot = makeTestBot()
-    const { connection, update, actions } = await receive(bot, { text: 'casino tonight', sender: { id: '777' } }, [
-      { name: 'Spam', keywords: ['casino'], action: BotRuleAction.Delete, order: 1 },
-    ])
-    const tools = botAgentTools({ update, bot: actions })
+    const { connection, update, actions } = await receive(bot, { text: 'casino tonight', sender: { id: '777' } })
+    // The id of the application's own keyword group the handler matched.
+    const ref = 'group-spam'
+    const tools = botAgentTools({ update, bot: actions, ref })
 
     for (const [name, args] of [
       [BotAgentTool.Reply, { text: 'Hello' }], [BotAgentTool.Delete, {}], [BotAgentTool.Warn, { text: 'No ads, please.' }],
@@ -25,16 +25,15 @@ describe('@owlmeans/bot-agent — botAgentTools', () => {
 
     const message = { chat: update.chat.id, message: update.message!.ref.id }
     const member = { chat: update.chat.id, user: '777' }
-    const rule = update.matches[0].rule.id
     const activity = (await bot.service.activity.list(bot.scope)).reverse()
-    expect(activity.map(entry => [entry.action, entry.ok, entry.update, entry.rule, entry.target, entry.text ?? null]))
+    expect(activity.map(entry => [entry.action, entry.ok, entry.update, entry.ref, entry.target, entry.text ?? null]))
       .toEqual([
-        [BotActionKind.Reply, true, update.id, rule, message, 'Hello'],
-        [BotActionKind.Delete, true, update.id, rule, message, null],
-        [BotActionKind.Reply, true, update.id, rule, message, 'No ads, please.'],
-        [BotActionKind.Mute, true, update.id, rule, member, null],
-        [BotActionKind.Ban, true, update.id, rule, member, null],
-        [BotActionKind.React, true, update.id, rule, message, '👎'],
+        [BotActionKind.Reply, true, update.id, ref, message, 'Hello'],
+        [BotActionKind.Delete, true, update.id, ref, message, null],
+        [BotActionKind.Reply, true, update.id, ref, message, 'No ads, please.'],
+        [BotActionKind.Mute, true, update.id, ref, member, null],
+        [BotActionKind.Ban, true, update.id, ref, member, null],
+        [BotActionKind.React, true, update.id, ref, message, '👎'],
       ])
     expect(activity.every(entry => entry.transport === BotTransport.Mock)).toBe(true)
     expect(telegramBotPlatform.mock.calls(connection).map(call => call.method)).toEqual(expect.arrayContaining([