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

package/src/tools.ts

@@ -0,0 +1,94 @@
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import type { JSONSchema } from '@langchain/core/utils/json_schema'
+import { toolHelper, type AgentToolSet, type ToolErrorResponse } from '@owlmeans/agent'
+import type { BotActionKind } from '@owlmeans/bot'
+import type { BotActionOptions, BotActionResult } from '@owlmeans/server-bot'
+import { BOT_AGENT_ACTIONS, BOT_AGENT_DONE, BOT_AGENT_TOOL_ACTIONS, BotAgentTool } from './consts.js'
+import { BOT_AGENT_MEMBER_TOOLS, BOT_AGENT_MESSAGE_TOOLS } from './consts.local.js'
+import type { BotAgentToolsOptions } from './types.js'
+import { BOT_AGENT_NO_REASON, BOT_AGENT_TOOL_DESCRIPTIONS } from './tools/consts.local.js'
+import {
+  BotAgentMuteSchema, BotAgentNoArgsSchema, BotAgentReactSchema, BotAgentTextSchema, BotAgentWarnSchema,
+} from './tools/schemas.js'
+import type { BotAgentToolArgs } from './tools/types.local.js'
+
+/**
+ * The bot's actions as agent tools, bound to ONE update — without the plugin, for a caller that
+ * assembles an agent's tools itself.
+ *
+ * A tool is offered only when its action is in `allow` (default: all), `bot.supports` it, and the
+ * 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.
+ */
+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 supported = (kind: BotActionKind): boolean => {
+    try {
+      return bot.supports(kind)
+    } catch {
+      return false
+    }
+  }
+
+  const offered = (name: BotAgentTool): boolean => {
+    const kind = BOT_AGENT_TOOL_ACTIONS[name]
+    if (!allowed.has(kind) || !supported(kind)) {
+      return false
+    }
+
+    return BOT_AGENT_MESSAGE_TOOLS.has(name) ? update.message != null
+      : BOT_AGENT_MEMBER_TOOLS.has(name) ? update.sender != null
+        : true
+  }
+
+  const textOf = (value: unknown): string => typeof value === 'string' ? value : ''
+
+  const define = (
+    name: BotAgentTool, schema: JSONSchema, perform: (args: BotAgentToolArgs) => Promise<BotActionResult>,
+  ): StructuredToolInterface => tool(
+    async (input: unknown): Promise<string | ToolErrorResponse> => {
+      try {
+        const args: BotAgentToolArgs = input != null && typeof input === 'object' ? input : {}
+        const result = await perform(args)
+        // The action's own sentence ("WhatsApp cannot delete messages."), never its machine `code`.
+        return result?.ok === true
+          ? BOT_AGENT_DONE
+          : { error: result?.error ?? BOT_AGENT_NO_REASON }
+      } catch (e) {
+        // BotActions never throw by contract; a broken one still must not take the run with it.
+        return toolHelper.toErrorResponse(e)
+      }
+    },
+    { name, description: BOT_AGENT_TOOL_DESCRIPTIONS[name], schema },
+  ) as unknown as StructuredToolInterface
+
+  const definitions: Record<BotAgentTool, () => StructuredToolInterface> = {
+    [BotAgentTool.Reply]: () => define(BotAgentTool.Reply, BotAgentTextSchema,
+      async ({ text }) => await bot.reply(update, textOf(text), opts)),
+    [BotAgentTool.Delete]: () => define(BotAgentTool.Delete, BotAgentNoArgsSchema,
+      async () => await bot.delete(update, opts)),
+    [BotAgentTool.Warn]: () => define(BotAgentTool.Warn, BotAgentWarnSchema,
+      async ({ text }) => await bot.reply(update, textOf(text), opts)),
+    [BotAgentTool.Mute]: () => define(BotAgentTool.Mute, BotAgentMuteSchema,
+      async ({ minutes }) => await bot.mute(update, { ...opts, minutes: Math.round(Number(minutes)) })),
+    [BotAgentTool.Ban]: () => define(BotAgentTool.Ban, BotAgentNoArgsSchema,
+      async () => await bot.ban(update, opts)),
+    [BotAgentTool.React]: () => define(BotAgentTool.React, BotAgentReactSchema,
+      async ({ emoji }) => await bot.react(update, textOf(emoji), opts)),
+  }
+
+  const tools: AgentToolSet = {}
+  for (const name of Object.values(BotAgentTool)) {
+    if (offered(name)) {
+      tools[name] = definitions[name]()
+    }
+  }
+
+  return tools
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { BotActionKind, BotUpdate } from '@owlmeans/bot'
+import type { BotActions } from '@owlmeans/server-bot'
+
+export interface BotAgentToolsOptions {
+  /** The update the tools act on: its message, its sender, its chat. */
+  update: BotUpdate
+  /**
+   * The connection's actions — the `bot` a handler receives, or `BotService.actions(update)`. They
+   * never throw: every call answers `{ ok, error? }` and records one activity.
+   */
+  bot: BotActions
+  /**
+   * What the model may do (`warn` is `reply`); default every action a tool performs. Intersected
+   * with `bot.supports(kind)`: a tool the platform cannot perform is never offered.
+   */
+  allow?: readonly BotActionKind[]
+}
+
+export interface BotAgentOptions extends BotAgentToolsOptions {
+  /** One more instruction, contributed after the matched groups' — the product's own rule for this agent. */
+  instruction?: string
+}

package/tests/_tools/model.ts

@@ -0,0 +1,49 @@
+import { AIMessageChunk } from '@langchain/core/messages'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+
+/**
+ * A model whose answers are decided in advance — the same double `@owlmeans/agent`'s own specs use
+ * (`FakeStreamingChatModel` always replays its first response and cannot drive a tool loop). It
+ * stands in for the MODEL, an external boundary, never for an `@owlmeans/*` package; the agent only
+ * asks a model for `bindTools` and `stream`, so that is all it implements.
+ */
+export interface ScriptedTurn {
+  content?: string
+  toolCalls?: Array<{ name: string, args: Record<string, unknown> }>
+}
+
+export interface ScriptedModel {
+  model: BaseChatModel
+  /** The message lists it was asked with, in order. */
+  asked: () => unknown[][]
+  /** The tool names the asking view was bound with, per ask — `null` for the unbound model. */
+  bound: () => Array<string[] | null>
+}
+
+export const scriptedModel = (script: ScriptedTurn[]): ScriptedModel => {
+  let at = 0
+  const asked: unknown[][] = []
+  const bound: Array<string[] | null> = []
+
+  const answer = (tools: string[] | null) => async (messages: unknown[]) => {
+    asked.push(messages)
+    bound.push(tools)
+    const turn = script[Math.min(at, script.length - 1)]
+    at += 1
+    const chunk = new AIMessageChunk({
+      content: turn.content ?? '',
+      tool_calls: (turn.toolCalls ?? []).map((call, index) => ({
+        name: call.name, args: call.args, id: `call_${at}_${index}`, type: 'tool_call' as const,
+      })),
+    })
+
+    return (async function* () { yield chunk })()
+  }
+
+  const model = {
+    bindTools: (tools: Array<{ name: string }>) => ({ ...model, stream: answer(tools.map(item => item.name)) }),
+    stream: answer(null),
+  }
+
+  return { model: model as unknown as BaseChatModel, asked: () => asked, bound: () => bound }
+}

package/tests/context.ts

@@ -0,0 +1,85 @@
+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 { 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,
+} from '@owlmeans/server-bot'
+import { createStaticResource } from '@owlmeans/static-resource'
+
+// Refused actions are expected here; `LOG_LEVEL=debug bun test` shows every line.
+configureLog({ level: process.env.LOG_LEVEL ?? 'error' })
+
+export interface TestBot {
+  context: BasicContext<BasicConfig>
+  service: BotService
+  scope: string
+}
+
+let stores = 0
+
+/**
+ * One real context per test: the four 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' })
+
+  return { context, service, scope: `scope-${randomUUID()}` }
+}
+
+/** A verified MOCK connection — no network, every platform call recorded. */
+export const connect = async (bot: TestBot, platform: BotPlatform = BotPlatform.Telegram): Promise<string> => {
+  const saved = await bot.service.connections.save(bot.scope, { platform, label: 'Guard', transport: BotTransport.Mock })
+  return (await bot.service.connections.verify(bot.scope, saved.id)).id
+}
+
+export interface Received {
+  connection: string
+  update: BotUpdate
+  actions: BotActions
+}
+
+/**
+ * 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.
+ */
+export const receive = async (
+  bot: TestBot, input: BotSimulateInput, rules: BotRuleInput[] = [], 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 }
+    await handle?.(update, actions, context)
+  })])
+  await bot.service.simulate(bot.scope, connection, input)
+  await runtime.dispatch()
+  await runtime.stop()
+  if (received == null) {
+    throw new Error('the simulated message was not dispatched')
+  }
+
+  return received
+}
+
+/**
+ * A WhatsApp customer's message on a verified mock connection, through server-bot's WhatsApp plugin —
+ * 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)

package/tests/helper.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+import { BotChatKind, BotRuleAction } 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('contextOf says what is absent rather than inventing it', 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[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')
+  })
+
+  test('promptOf names the platform and the chat, and the tools\' answers', async () => {
+    const bot = makeTestBot()
+    const { update } = await receive(bot, { text: 'hello', chat: { title: 'Gamers' } })
+
+    expect(botAgentHelper.promptOf(update)).toStartWith('A message arrived in the Telegram chat "Gamers". ')
+    expect(botAgentHelper.promptOf(update)).toContain('"done"')
+  })
+})

package/tests/loop.spec.ts

@@ -0,0 +1,103 @@
+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 { 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 { 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 '
+  + 'keyword groups\' instructions and act only through your tools.'
+
+/** The shape a target's agent module has: one execution, one prompt service, the model handed in. */
+const executions = makeExecutionService('bot-agent-loop-exec')
+const prompts = makePromptService({}, 'bot-agent-loop-prompts')
+const exec = executions.root({
+  models: () => { throw new Error('the agent asks agentModel only') },
+  prompts: () => prompts,
+  policy: { effort: DEFAULT_EFFORT },
+  purpose: { type: 'moderator' },
+  prompt: { role: ROLE },
+})
+
+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 },
+]
+
+/** A message simulated on a mock Telegram connection; the handler runs the agent over it. */
+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 agent = makeModeratorAgent(scripted)
+    agent.use(botAgentPlugin({
+      update, bot: actions, allow: [BotActionKind.Delete, BotActionKind.Reply, BotActionKind.Mute],
+    }))
+    result = await agent.invoke(botAgentHelper.promptOf(update), { action: 'moderate' })
+  })
+  if (result == null) {
+    throw new Error('the agent did not run')
+  }
+  const tools = (result as AgentResult).messages.filter(message => message.getType() === 'tool') as ToolMessage[]
+
+  return { bot, scripted, received, result: result as AgentResult, tools }
+}
+
+describe('@owlmeans/bot-agent — an agent loop over a bot update', () => {
+  test('the agent reads the message from its context and acts through the tools', async () => {
+    const { bot, scripted, received, result, tools } = await moderate('Best casino in town', [
+      {
+        toolCalls: [
+          { name: BotAgentTool.Delete, args: {} },
+          { name: BotAgentTool.Warn, args: { text: 'Advertising is not allowed here.' } },
+        ],
+      },
+      { content: 'Deleted the casino ad and warned the sender.' },
+    ])
+
+    // Bound with exactly the allowed tools the platform supports, every round.
+    expect(scripted.bound()).toEqual([
+      [BotAgentTool.Reply, BotAgentTool.Delete, BotAgentTool.Warn, BotAgentTool.Mute],
+      [BotAgentTool.Reply, BotAgentTool.Delete, BotAgentTool.Warn, BotAgentTool.Mute],
+    ])
+    // The persona in the system message; the message and its group in the project message after it.
+    const [system, project] = scripted.asked()[0] as Array<{ getType: () => string, content: unknown }>
+    expect(system.getType()).toBe('system')
+    expect(JSON.stringify(system.content)).toContain('You moderate a community chat')
+    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(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.'],
+    ])
+  })
+
+  test('a refused or unoffered tool comes back to the model as an error and the run goes on', async () => {
+    const { bot, tools, result } = await moderate('casino again', [
+      { toolCalls: [{ name: BotAgentTool.Mute, args: { minutes: 0 } }, { name: BotAgentTool.Ban, args: {} }] },
+      { content: 'Could not mute; banning is not mine to do.' },
+    ])
+
+    expect(tools.map(message => [message.name, message.status])).toEqual([
+      [BotAgentTool.Mute, 'error'], [BotAgentTool.Ban, 'error'],
+    ])
+    expect(tools[0].content).toBe('A mute lasts at least one minute.')
+    expect(tools[1].content).toContain('Tool ban not found')
+    expect(result.message.content).toBe('Could not mute; banning is not mine to do.')
+    expect((await bot.service.activity.list(bot.scope)).map(entry => [entry.action, entry.ok]))
+      .toEqual([[BotActionKind.Mute, false]])
+  })
+})

package/tests/plugin.spec.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test'
+import { makeAgentModel, type AgentRun } from '@owlmeans/agent'
+import { BotActionKind, BotRuleAction } 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 { 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 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 () => {
+    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)
+
+    expect(rest).toEqual([])
+    expect(message).toContain('Platform: Telegram')
+    expect(message).toContain('Chat: group "Gamers"')
+    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.')
+  })
+
+  test('offers only the tools the platform supports and allow names', async () => {
+    const bot = makeTestBot()
+    const telegram = await receive(bot, { text: 'casino' }, RULES)
+    const whatsApp = await whatsAppUpdate(bot)
+    const names = (options: Parameters<typeof botAgentPlugin>[0]): string[] =>
+      Object.values(botAgentPlugin(options).tools!(NO_RUN)).map(item => item.name)
+
+    expect(names({ update: telegram.update, bot: telegram.actions })).toEqual([
+      BotAgentTool.Reply, BotAgentTool.Delete, BotAgentTool.Warn, BotAgentTool.Mute, BotAgentTool.Ban, BotAgentTool.React,
+    ])
+    expect(names({ update: telegram.update, bot: telegram.actions, allow: [BotActionKind.Delete, BotActionKind.Mute] }))
+      .toEqual([BotAgentTool.Delete, BotAgentTool.Mute])
+    // WhatsApp can reply and react — never delete, mute or ban — and `warn` is a reply.
+    expect(names({ update: whatsApp.update, bot: whatsApp.actions })).toEqual([
+      BotAgentTool.Reply, BotAgentTool.Warn, BotAgentTool.React,
+    ])
+    expect(names({ update: whatsApp.update, bot: whatsApp.actions, allow: [BotActionKind.Delete, BotActionKind.Ban] }))
+      .toEqual([])
+  })
+
+  test('keeps one alias: registering it for the next update replaces the previous one', async () => {
+    const bot = makeTestBot()
+    const first = await receive(bot, { text: 'the first message' })
+    const second = await receive(bot, { text: 'the second message' })
+    const scripted = scriptedModel([{ content: 'nothing to do' }])
+    const agent = makeAgentModel({
+      exec: makeExecutionService('bot-agent-alias-exec').root({
+        models: () => { throw new Error('the agent asks agentModel only') },
+        prompts: () => makePromptService({}, 'bot-agent-alias-prompts'),
+        policy: { effort: DEFAULT_EFFORT },
+        purpose: { type: 'bot-agent-spec' },
+        prompt: { role: 'You moderate a chat.' },
+      }),
+      agentModel: scripted.model,
+      tools: {},
+    })
+
+    agent.use(botAgentPlugin({ update: first.update, bot: first.actions }))
+    agent.use(botAgentPlugin({ update: second.update, bot: second.actions }))
+    await agent.invoke('act')
+
+    expect(botAgentPlugin({ update: first.update, bot: first.actions }).alias).toBe(BOT_AGENT_PLUGIN)
+    const asked = JSON.stringify(scripted.asked()[0])
+    expect(asked).toContain('the second message')
+    expect(asked).not.toContain('the first message')
+    expect(asked.split('# The chat message').length - 1).toBe(1)
+  })
+})

package/tests/tools.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test'
+import { toolHelper } from '@owlmeans/agent'
+import { BotActionKind, BotRuleAction, 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'
+
+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 () => {
+    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 })
+
+    for (const [name, args] of [
+      [BotAgentTool.Reply, { text: 'Hello' }], [BotAgentTool.Delete, {}], [BotAgentTool.Warn, { text: 'No ads, please.' }],
+      [BotAgentTool.Mute, { minutes: 60 }], [BotAgentTool.Ban, {}], [BotAgentTool.React, { emoji: '👎' }],
+    ] as const) {
+      expect(await toolHelper.safeInvokeTool(tools, callOf(name, args))).toBe(BOT_AGENT_DONE)
+    }
+
+    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]))
+      .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, '👎'],
+      ])
+    expect(activity.every(entry => entry.transport === BotTransport.Mock)).toBe(true)
+    expect(telegramBotPlatform.mock.calls(connection).map(call => call.method)).toEqual(expect.arrayContaining([
+      'sendMessage', 'deleteMessage', 'restrictChatMember', 'banChatMember', 'setMessageReaction',
+    ]))
+  })
+
+  test('a refused action answers what went wrong instead of throwing', async () => {
+    const bot = makeTestBot()
+    const { connection, update, actions } = await receive(bot, { text: 'hello' })
+    const tools = botAgentTools({ update, bot: actions })
+
+    expect(await toolHelper.safeInvokeTool(tools, callOf(BotAgentTool.Reply, { text: ' ' })))
+      .toEqual({ error: 'The text is empty.' })
+    expect(await toolHelper.safeInvokeTool(tools, callOf(BotAgentTool.Mute, { minutes: 0 })))
+      .toEqual({ error: 'A mute lasts at least one minute.' })
+    // A wrong argument type never reaches the action: the schema refuses it, readable.
+    expect(toolHelper.isToolError(await toolHelper.safeInvokeTool(tools, callOf(BotAgentTool.Mute, { minutes: 'soon' }))))
+      .toBe(true)
+
+    // The connection switched off between the update and the agent's decision.
+    await bot.service.connections.save(bot.scope, { id: connection, platform: update.platform, label: 'Guard', enabled: false })
+    const disabled = botAgentTools({ update, bot: await bot.service.actions(update) })
+    const answer = await disabled[BotAgentTool.Delete].invoke({})
+    expect(answer).toEqual({ error: 'The bot connection is switched off.' })
+  })
+
+  test('offers no message tool without a message and no member tool without a sender', async () => {
+    const bot = makeTestBot()
+    const { update, actions } = await receive(bot, { text: 'hello' })
+    const names = (patch: object): string[] =>
+      Object.values(botAgentTools({ update: { ...update, ...patch }, bot: actions })).map(item => item.name)
+
+    expect(names({ message: undefined })).toEqual([BotAgentTool.Mute, BotAgentTool.Ban])
+    expect(names({ sender: undefined }))
+      .toEqual([BotAgentTool.Reply, BotAgentTool.Delete, BotAgentTool.Warn, BotAgentTool.React])
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.server.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}