manychat-ai-agent 0.17.1 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.18.1](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.18.0...v0.18.1) (2026-10-07)
+
+
+### Specs and Docs
+
+* add a getting-started guide for npm create, and point to it from the top of the README ([893e8da](https://github.com/pedronastasi/manychat-ai-agent/commit/893e8dac5a668d6e20ae2439822894a4c3aaa71d))
+* derive a top bar, collapse the long sidebar groups, and fix badge and heading styling on the site ([2faca35](https://github.com/pedronastasi/manychat-ai-agent/commit/2faca35920a98ecbe7e8d3e4ec1e5a45372068b5))
+* derive nav bar from sections, collapse long groups, add getting-started guide ([31a3fde](https://github.com/pedronastasi/manychat-ai-agent/commit/31a3fde37dcee03b7847f21523114335623bc036))
+
+## [0.18.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.17.1...v0.18.0) (2026-10-06)
+
+
+### Features
+
+* finish plugin tools, and move plugin channels to spec 038 (spec 036) ([712c860](https://github.com/pedronastasi/manychat-ai-agent/commit/712c8603a291da1b0af3a980d30d2b0958e84d7d))
+* finish plugin tools, and move plugin channels to spec 038 (spec 036) ([1908609](https://github.com/pedronastasi/manychat-ai-agent/commit/190860916fffaea797571226647672a2a2b5751d))
+
+
+### Specs and Docs
+
+* record PR 182 in spec 036 ([2ab0918](https://github.com/pedronastasi/manychat-ai-agent/commit/2ab0918a8bd5beadcf2498ac1065e8b042a9a819))
+
 ## [0.17.1](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.17.0...v0.17.1) (2026-10-06)
 
 

package/README.md

@@ -29,6 +29,17 @@ and an embedded [PGlite](https://pglite.dev/) Postgres. In another terminal,
 
 ![pnpm simulate answering a price question from the catalog and escalating a request for a person](docs/assets/demo.svg)
 
+That clone is for trying the agent and working on it. To run one for your own
+business, generate a project of your own instead, which depends on the published
+package rather than a copy of this repository:
+
+```bash
+npm create manychat-ai-agent@latest my-agent
+```
+
+[Starting a new agent](docs/guides/getting-started.md) walks through it,
+from the offline first run to a deployment.
+
 ---
 
 ## The problem this solves
@@ -366,7 +377,8 @@ It writes `config/`, an offline `.env`, an eval suite, CI, Compose and
 Renovate, depending on the agent and its image at the scaffolder's version.
 Replace `config/` with your own and keep the repository private: the generated
 CI fails when it is public
-([specs/035](specs/035-create-scaffolds-a-tenant-project.md)).
+([specs/035](specs/035-create-scaffolds-a-tenant-project.md)). The steps are in
+[Starting a new agent](docs/guides/getting-started.md).
 
 Point a ManyChat **Dynamic Block** (Dev Tools, requires a Pro plan) at
 `POST /v1/channels/manychat/message` and add an `Authorization: Bearer <secret>`

package/dist/agent/prompt.d.ts

@@ -24,7 +24,11 @@ export interface SystemPromptParts {
  */
 export declare function buildSystemPrompt(persona: string, catalog: Catalog, rules: Rules, 
 /** This tenant's `tools.json` (specs/012); its funnel adds the SALES rules (specs/023). */
-tools?: Tools): SystemPromptParts;
+tools?: Tools, 
+/** Whether the deployment's plugins add tools of their own (specs/036). */
+options?: {
+    pluginTools?: boolean;
+}): SystemPromptParts;
 declare const NUDGE_NOTE_OPEN = "[no reply from the contact since";
 /**
  * The trigger of a nudge turn, in place of a contact message (specs/025 § A

package/dist/agent/prompt.js

@@ -58,8 +58,10 @@ function renderCatalog(catalog) {
  */
 export function buildSystemPrompt(persona, catalog, rules, 
 /** This tenant's `tools.json` (specs/012); its funnel adds the SALES rules (specs/023). */
-tools = NO_TOOLS) {
-    const withTools = offersTools(tools);
+tools = NO_TOOLS, 
+/** Whether the deployment's plugins add tools of their own (specs/036). */
+options = {}) {
+    const withTools = offersTools(tools) || options.pluginTools === true;
     const staticPrefix = [
         persona.trim(),
         '',
@@ -112,6 +114,7 @@ tools = NO_TOOLS) {
         'someone who has declined twice, or a turn whose opening flow asks it.',
         'Null is a decision, not a way to skip the field.',
         ...(withTools ? ACTIONS_SECTION : []),
+        ...(options.pluginTools ? PLUGIN_TOOLS_LINES : []),
         ...intentSection(tools),
         ...salesSection(tools),
         ...coursesSection(tools),
@@ -141,6 +144,14 @@ const ACTIONS_SECTION = [
     'writes that line, not you: it lists what reached ManyChat on that turn. Do not',
     'repeat those actions unless the contact asks, and never write such a line.',
 ];
+/**
+ * Only when a plugin adds a tool, so a deployment without one gets the prompt
+ * it had before (specs/036).
+ */
+const PLUGIN_TOOLS_LINES = [
+    'This deployment adds tools of its own. They are staged like the others: performed',
+    'after your reply, and not at all if you escalate. Their description says when to use them.',
+];
 const NUDGE_NOTE_OPEN = '[no reply from the contact since';
 /**
  * How the model schedules and writes a follow-up (specs/025). Only present

package/dist/agent/runner.d.ts

@@ -7,6 +7,7 @@ import type { ContactReads } from './contact.ts';
 import type { FlowSends } from './flows.ts';
 import { ActionStage } from './tools.ts';
 import type { ContactActions } from './tools.ts';
+import type { Plugins } from '../plugins/plugins.ts';
 export interface AgentUsage {
     inputTokens: number | undefined;
     outputTokens: number | undefined;
@@ -125,6 +126,8 @@ export interface RunnerOptions {
      * what Constitution C5 forbids. Enable only against a trusted collector.
      */
     recordPromptsInTraces?: boolean;
+    /** The tenant's plugin tools, loaded once at boot (specs/036). */
+    plugins?: Plugins | undefined;
 }
 export declare class GenerateTextRunner implements AgentRunner {
     private readonly opts;

package/dist/agent/runner.js

@@ -91,11 +91,12 @@ export class GenerateTextRunner {
         const config = this.opts.config();
         if (this.cached?.config !== config) {
             const tools = config.tools ?? NO_TOOLS;
-            const withTools = offersTools(tools);
+            const pluginTools = this.opts.plugins?.hasTools ?? false;
+            const withTools = offersTools(tools) || pluginTools;
             this.cached = {
                 config,
                 withTools,
-                ...buildSystemPrompt(config.persona, config.catalog, config.rules, tools),
+                ...buildSystemPrompt(config.persona, config.catalog, config.rules, tools, { pluginTools }),
             };
         }
         return this.cached;
@@ -110,6 +111,7 @@ export class GenerateTextRunner {
                 nudgeTurn: nudge !== undefined,
                 flows,
                 beforeFlow,
+                plugins: this.opts.plugins,
             })
             : undefined;
         // The opening is no longer known before the loop runs: the prospect write

package/dist/agent/tools.d.ts

@@ -3,6 +3,7 @@ import type { Tools, INTENT_VALUES } from '../contracts/config.ts';
 import type { ActionRecord, ActionStatus, PerformableAction, StagedAction } from '../contracts/agent.ts';
 import type { ContactReads } from './contact.ts';
 import type { FlowSends, SendFlowAction } from './flows.ts';
+import type { Plugins } from '../plugins/plugins.ts';
 /**
  * Steps one to three may call tools; step four offers none, so it must
  * produce the reply. Four fit read, act, read again and reply (specs/024
@@ -235,4 +236,6 @@ options?: {
      * (specs/032 § The opening flow is the server's, not the model's).
      */
     beforeFlow?: (() => Promise<void>) | undefined;
+    /** The tenant's plugin tools, staged as the built-in ones are (specs/036). */
+    plugins?: Plugins | undefined;
 }): ToolSet | undefined;

package/dist/agent/tools.js

@@ -685,5 +685,8 @@ options = {}) {
                 },
         });
     }
+    // Added last, and a built-in name was refused when the plugin loaded, so a
+    // plugin can neither replace nor shadow one of the tools above.
+    options.plugins?.addTools(tools, stage, closed, description => `${description}\n${STAGED}`);
     return Object.keys(tools).length > 0 ? tools : undefined;
 }

package/dist/channels/manychat/client.js

@@ -118,6 +118,9 @@ export class ManyChatHttpClient {
                 // A row in `nudges`, written by NudgingPerformer (specs/025). Reaching
                 // ManyChat with one means the wrapper was left out.
                 throw new Error('schedule_nudge is not a ManyChat action');
+            case 'plugin':
+                // Performed by its plugin (specs/036); the same mistake as above.
+                throw new Error('a plugin tool is not a ManyChat action');
         }
     }
     /**

package/dist/cli/run.js

@@ -90,7 +90,22 @@ export async function run(argv) {
             return undefined;
         }
         case 'config check': {
-            console.log(`config check passed (${configDir})`);
+            // Plugins are checked as `agent serve` loads them, so a check that
+            // passes is a boot that does not stop on one (specs/036).
+            const { loadPlugins } = await import("../plugins/loader.js");
+            let names;
+            try {
+                names = (await loadPlugins(configDir)).names;
+            }
+            catch (error) {
+                if (error instanceof ConfigError) {
+                    console.error(`invalid plugins (${configDir}): ${error.message}`);
+                    return 1;
+                }
+                throw error;
+            }
+            const loaded = names.length > 0 ? `; plugins: ${names.join(', ')}` : '';
+            console.log(`config check passed (${configDir}${loaded})`);
             return 0;
         }
         case 'upgrade': {
@@ -119,9 +134,11 @@ async function startWorkers(configDir) {
     const { resolveModel } = await import("../agent/registry.js");
     const { ConfigStore } = await import("../config/loader.js");
     const { createLogger } = await import("../observability/logger.js");
+    const { loadPlugins } = await import("../plugins/loader.js");
     const env = loadEnv();
     const logger = createLogger(env.LOG_LEVEL);
     const configStore = new ConfigStore(configDir, reservedNames(env));
+    const plugins = await loadPlugins(configDir);
     let db;
     if (dbMod.isEmbedded(env.DATABASE_URL)) {
         const embedded = await dbMod.createEmbeddedDatabase(env.DATABASE_URL);
@@ -141,8 +158,9 @@ async function startWorkers(configDir) {
         maxOutputTokens: env.AGENT_MAX_OUTPUT_TOKENS,
         temperature: env.AGENT_TEMPERATURE,
         reasoningEffort: env.AGENT_REASONING_EFFORT,
+        plugins,
     });
-    const stopOutbox = new OutboxWorker({ db, client: manychat, logger }).start();
+    const stopOutbox = new OutboxWorker({ db, client: manychat, logger, plugins }).start();
     const stopNudges = new NudgeWorker({
         db,
         runner,

package/dist/contracts/agent.d.ts

@@ -146,7 +146,8 @@ export type ToolName = z.infer<typeof ToolName>;
  * What a turn's `actions` entry may record: a tool the model called, or a
  * `send_event`, which no model is ever offered. The server performs it as a
  * follow-on of a funnel write (specs/027 § Every event is recorded beside the
- * write that caused it).
+ * write that caused it). A plugin tool is recorded as `plugin`, its name as
+ * the id (specs/036).
  */
 export declare const ActionKind: z.ZodEnum<{
     send_flow: "send_flow";
@@ -156,6 +157,7 @@ export declare const ActionKind: z.ZodEnum<{
     write_note: "write_note";
     schedule_nudge: "schedule_nudge";
     send_event: "send_event";
+    plugin: "plugin";
 }>;
 export type ActionKind = z.infer<typeof ActionKind>;
 /**
@@ -234,6 +236,12 @@ export declare const StagedAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
     tool: z.ZodLiteral<"schedule_nudge">;
     id: z.ZodString;
     minutes: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    tool: z.ZodLiteral<"plugin">;
+    id: z.ZodString;
+    plugin: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    notes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>], "tool">;
 export type StagedAction = z.infer<typeof StagedAction>;
 /** Everything that may reach ManyChat as an action: a staged one, or a follow-on event (specs/027). */
@@ -263,6 +271,7 @@ export declare const ActionRecord: z.ZodObject<{
         write_note: "write_note";
         schedule_nudge: "schedule_nudge";
         send_event: "send_event";
+        plugin: "plugin";
     }>;
     id: z.ZodString;
     value: z.ZodOptional<z.ZodString>;

package/dist/contracts/agent.js

@@ -146,9 +146,10 @@ export const ToolName = z.enum([
  * What a turn's `actions` entry may record: a tool the model called, or a
  * `send_event`, which no model is ever offered. The server performs it as a
  * follow-on of a funnel write (specs/027 § Every event is recorded beside the
- * write that caused it).
+ * write that caused it). A plugin tool is recorded as `plugin`, its name as
+ * the id (specs/036).
  */
-export const ActionKind = z.enum([...ToolName.options, 'send_event']);
+export const ActionKind = z.enum([...ToolName.options, 'send_event', 'plugin']);
 /**
  * An action the model staged, resolved against `tools.json` at the moment it
  * was staged. Carries the ManyChat names it will be performed with, so it
@@ -224,6 +225,19 @@ export const StagedAction = z.discriminatedUnion('tool', [
      * `nudges`, never as a ManyChat request (specs/025).
      */
     z.object({ tool: z.literal('schedule_nudge'), id: z.string(), minutes: z.number() }),
+    /**
+     * A tool a tenant's plugin declares, `id` being its name. Its parameters
+     * were validated against the declaration when it was staged, and its notes
+     * cleaned and kept apart so they can be kept out of the logs as a
+     * `write_note`'s text is. The plugin performs it, never ManyChat (specs/036).
+     */
+    z.object({
+        tool: z.literal('plugin'),
+        id: z.string(),
+        plugin: z.string(),
+        params: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+        notes: z.record(z.string(), z.string()).optional(),
+    }),
 ]);
 /** What became of a staged action (specs/012 § Every staged action is recorded on its turn). */
 export const ActionStatus = z.enum([

package/dist/conversation/actions.js

@@ -10,7 +10,13 @@ function reasonFor(error, subscriberId, action) {
     // A ManyChat error's message already names the endpoint, the status and
     // ManyChat's own message.
     const raw = error instanceof Error ? error.message : String(error);
-    const unquoted = action.tool === 'write_note' ? raw.split(action.text).join('[note]') : raw;
+    // A plugin's own error can quote anything it was given (specs/036).
+    const quoted = action.tool === 'write_note'
+        ? [action.text]
+        : action.tool === 'plugin'
+            ? Object.values(action.notes ?? {})
+            : [];
+    const unquoted = quoted.reduce((text, value) => (value.length > 0 ? text.split(value).join('[note]') : text), raw);
     return redactText(unquoted.split(subscriberId).join('[subscriber]')).slice(0, 200);
 }
 /**

package/dist/conversation/store.d.ts

@@ -83,7 +83,7 @@ export declare class ConversationStore {
     actionHistory(conversationId: string): Promise<{
         createdAt: Date;
         actions: {
-            tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event";
+            tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event" | "plugin";
             id: string;
             status: "staged" | "performed" | "failed" | "discarded" | "dropped_over_cap" | "dead_lettered";
             value?: string | undefined;
@@ -109,7 +109,7 @@ export declare class ConversationStore {
         role: "user" | "agent";
         text: string;
         actions: {
-            tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event";
+            tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event" | "plugin";
             id: string;
             status: "staged" | "performed" | "failed" | "discarded" | "dropped_over_cap" | "dead_lettered";
             value?: string | undefined;

package/dist/db/schema.d.ts

@@ -427,7 +427,7 @@ export declare const turns: import("drizzle-orm/pg-core").PgTableWithColumns<{
             dataType: "json";
             columnType: "PgJsonb";
             data: {
-                tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event";
+                tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event" | "plugin";
                 id: string;
                 status: "staged" | "performed" | "failed" | "discarded" | "dropped_over_cap" | "dead_lettered";
                 value?: string | undefined;
@@ -448,7 +448,7 @@ export declare const turns: import("drizzle-orm/pg-core").PgTableWithColumns<{
             generated: undefined;
         }, {}, {
             $type: {
-                tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event";
+                tool: "send_flow" | "add_tag" | "remove_tag" | "set_field" | "write_note" | "schedule_nudge" | "send_event" | "plugin";
                 id: string;
                 status: "staged" | "performed" | "failed" | "discarded" | "dropped_over_cap" | "dead_lettered";
                 value?: string | undefined;

package/dist/evals/runner.js

@@ -1,6 +1,7 @@
 import { loadEnv, loadTenantConfig } from "../config/loader.js";
 import { resolveModel } from "../agent/registry.js";
 import { GenerateTextRunner } from "../agent/runner.js";
+import { loadPlugins } from "../plugins/loader.js";
 import { ActionStage, describeAction } from "../agent/tools.js";
 import { checkCase, classify, evalDir, loadCases } from "./cases.js";
 /** When a nudge case's contact went quiet (specs/025). Invented, and fixed. */
@@ -20,6 +21,9 @@ export async function runEval() {
     const configDir = process.env.CONFIG_DIR ?? 'config';
     const suiteDir = evalDir();
     const tenant = loadTenantConfig(configDir);
+    // Offered as in production, so a suite can assert a plugin tool is chosen.
+    // Nothing staged here is performed (specs/036).
+    const plugins = await loadPlugins(configDir);
     const cases = loadCases(suiteDir);
     // Defaults to the race deadline, so a suite that sets nothing behaves as
     // before. A tenant evaluating a reasoning model raises this rather than
@@ -32,6 +36,7 @@ export async function runEval() {
         maxOutputTokens: env.AGENT_MAX_OUTPUT_TOKENS,
         temperature: env.AGENT_TEMPERATURE,
         reasoningEffort: env.AGENT_REASONING_EFFORT,
+        plugins,
     });
     console.log(`\n  model: ${env.AGENT_MODEL}   suite: ${suiteDir}   cases: ${cases.length}\n`);
     const outcomes = [];

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The bare `manychat-ai-agent` entry point: the plugin API (specs/036). The
+ * agent itself is run through its CLI or image, never imported.
+ */
+export { definePlugin, defineTool, PLUGIN_API_VERSION } from './plugins/api.ts';
+export type { ParamsOf, Plugin, PluginCall, PluginLogger, PluginParameter, PluginParameters, PluginTool, } from './plugins/api.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * The bare `manychat-ai-agent` entry point: the plugin API (specs/036). The
+ * agent itself is run through its CLI or image, never imported.
+ */
+export { definePlugin, defineTool, PLUGIN_API_VERSION } from "./plugins/api.js";

package/dist/main.js

@@ -14,11 +14,15 @@ import { manychatClientFor } from "./channels/manychat/client.js";
 import { OutboxWorker } from "./outbox/worker.js";
 import { NudgeWorker } from "./nudge/worker.js";
 import { buildServer } from "./server.js";
+import { loadPlugins } from "./plugins/loader.js";
 export async function main() {
     const env = loadEnv();
     // A tool aimed at the reply flow or field fails the boot, and a reload that
     // introduces one is refused (specs/012).
-    const configStore = new ConfigStore(process.env.CONFIG_DIR ?? 'config', reservedNames(env));
+    const configDir = process.env.CONFIG_DIR ?? 'config';
+    const configStore = new ConfigStore(configDir, reservedNames(env));
+    // Code, loaded once: a plugin that does not load stops the boot (specs/036).
+    const plugins = await loadPlugins(configDir);
     let db;
     if (isEmbedded(env.DATABASE_URL)) {
         const embedded = await createEmbeddedDatabase(env.DATABASE_URL);
@@ -36,6 +40,7 @@ export async function main() {
         configStore,
         manychat,
         contacts: manychat,
+        plugins,
     });
     const migrated = await runMigrations(db);
     if (migrated.length > 0)
@@ -44,6 +49,7 @@ export async function main() {
         db,
         client: manychat,
         logger: app.log,
+        plugins,
     }).start();
     // Follow-ups the agent scheduled (specs/025). Idle for a tenant without a
     // `nudge` section: nothing schedules one.

package/dist/outbox/worker.d.ts

@@ -1,5 +1,6 @@
 import type { Database } from '../db/client.ts';
 import type { ManyChatClient } from '../channels/manychat/client.ts';
+import type { Plugins } from '../plugins/plugins.ts';
 export interface WorkerLogger {
     info: (obj: object, msg: string) => void;
     warn: (obj: object, msg: string) => void;
@@ -9,6 +10,8 @@ export interface WorkerOptions {
     db: Database;
     client: ManyChatClient;
     logger: WorkerLogger;
+    /** Performs the plugin actions deferred with a reply (specs/036). */
+    plugins?: Plugins | undefined;
     batchSize?: number;
     pollIntervalMs?: number;
 }
@@ -26,6 +29,7 @@ export declare class OutboxWorker {
     private readonly tokens;
     private readonly store;
     private readonly nudges;
+    private readonly actions;
     private running;
     /**
      * Set by the stop function. A contact's rows after the one being sent go

package/dist/outbox/worker.js

@@ -12,6 +12,7 @@ export class OutboxWorker {
     tokens;
     store;
     nudges;
+    actions;
     running = false;
     /**
      * Set by the stop function. A contact's rows after the one being sent go
@@ -26,6 +27,7 @@ export class OutboxWorker {
         this.tokens = new ContactTokens(opts.db, opts.client);
         this.store = new ConversationStore(opts.db);
         this.nudges = new NudgeStore(opts.db);
+        this.actions = opts.plugins ? opts.plugins.performer(opts.client, opts.logger) : opts.client;
     }
     /**
      * The actions deferred with a reply, performed once, after its first
@@ -39,8 +41,8 @@ export class OutboxWorker {
             return;
         try {
             const performer = row.conversationId
-                ? new NudgingPerformer(this.opts.client, this.nudges, row.conversationId)
-                : this.opts.client;
+                ? new NudgingPerformer(this.actions, this.nudges, row.conversationId)
+                : this.actions;
             const outcomes = await performActions(performer, row.subscriberId, actions, this.opts.logger);
             if (turnId)
                 await this.store.resolveStaged(turnId, outcomes);

package/dist/plugins/api.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The plugin API: what a tenant project's plugin package exports, imported
+ * from the bare `manychat-ai-agent` entry point (specs/036).
+ *
+ * A plugin adds tools. Each is staged when the model calls it and performed
+ * after the reply, exactly as the built-in tools of specs/012 are, so a plugin
+ * gets no more power than one of them has.
+ */
+/** The plugin API this agent implements. A plugin naming another is refused at startup. */
+export declare const PLUGIN_API_VERSION = 1;
+/**
+ * One parameter of a plugin tool. There is no free-text string: text is a
+ * `note`, bounded and cleaned as a `tools.json` note is (specs/012 § Free-text
+ * field values are refused, ADR-0017).
+ */
+export type PluginParameter = {
+    type: 'enum';
+    values: readonly [string, ...string[]];
+    description?: string;
+    optional?: boolean;
+} | {
+    type: 'number';
+    integer?: boolean;
+    min?: number;
+    max?: number;
+    description?: string;
+    optional?: boolean;
+} | {
+    type: 'boolean';
+    description?: string;
+    optional?: boolean;
+} | {
+    type: 'note';
+    /** At most `MAX_NOTE_LENGTH` (500), as a `tools.json` note. */
+    maxLength: number;
+    description?: string;
+    optional?: boolean;
+};
+export type PluginParameters = Readonly<Record<string, PluginParameter>>;
+type ValueOf<P extends PluginParameter> = P extends {
+    type: 'enum';
+    values: readonly (infer V)[];
+} ? V : P extends {
+    type: 'number';
+} ? number : P extends {
+    type: 'boolean';
+} ? boolean : string;
+/** The validated values `perform` receives, typed from the declared parameters. */
+export type ParamsOf<S extends PluginParameters> = {
+    [K in keyof S as S[K] extends {
+        optional: true;
+    } ? never : K]: ValueOf<S[K]>;
+} & {
+    [K in keyof S as S[K] extends {
+        optional: true;
+    } ? K : never]?: ValueOf<S[K]>;
+};
+/**
+ * The agent's own redacting logger, scoped to the plugin. Message and string
+ * fields are redacted before they are written (C5).
+ */
+export interface PluginLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * Everything `perform` is given: the turn's subscriber, never one the model
+ * named; the validated parameters; the logger; and a signal that aborts when
+ * the agent stops waiting. No model, prompt, catalog or database.
+ */
+export interface PluginCall<P> {
+    subscriberId: string;
+    params: P;
+    logger: PluginLogger;
+    signal: AbortSignal;
+}
+export interface PluginTool<S extends PluginParameters = PluginParameters> {
+    /** Lowercase snake case, unique, and not a built-in tool's name. */
+    name: string;
+    /** What the model reads to decide when to call it. */
+    description: string;
+    parameters: S;
+    /**
+     * Runs after the reply is sent, once. A failure is logged and recorded on
+     * the turn, never retried (specs/012 § A failed action is logged, never retried).
+     */
+    perform(call: PluginCall<ParamsOf<S>>): Promise<void> | void;
+}
+export interface Plugin {
+    name: string;
+    /** The plugin API it was written against: `PLUGIN_API_VERSION`. */
+    apiVersion: number;
+    tools?: readonly PluginTool<any>[];
+}
+/**
+ * A plugin package's default export. Returns the plugin unchanged: the agent
+ * checks it when it loads, so a plain object passes or fails the same way.
+ */
+export declare function definePlugin<const P extends Plugin>(plugin: P): P;
+/** Types a tool's `perform` from its parameters. Returns the tool unchanged. */
+export declare function defineTool<const S extends PluginParameters>(tool: PluginTool<S>): PluginTool<S>;
+export {};

package/dist/plugins/api.js

@@ -0,0 +1,21 @@
+/**
+ * The plugin API: what a tenant project's plugin package exports, imported
+ * from the bare `manychat-ai-agent` entry point (specs/036).
+ *
+ * A plugin adds tools. Each is staged when the model calls it and performed
+ * after the reply, exactly as the built-in tools of specs/012 are, so a plugin
+ * gets no more power than one of them has.
+ */
+/** The plugin API this agent implements. A plugin naming another is refused at startup. */
+export const PLUGIN_API_VERSION = 1;
+/**
+ * A plugin package's default export. Returns the plugin unchanged: the agent
+ * checks it when it loads, so a plain object passes or fails the same way.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}
+/** Types a tool's `perform` from its parameters. Returns the tool unchanged. */
+export function defineTool(tool) {
+    return tool;
+}

package/dist/plugins/loader.d.ts

@@ -0,0 +1,20 @@
+import { ConfigError } from '../config/loader.ts';
+import { Plugins } from './plugins.ts';
+/** The optional tenant file that lists the plugin packages to load (specs/036). */
+export declare const PLUGINS_FILE = "plugins.json";
+/** A plugin that cannot be loaded. A `ConfigError`, so every command reports it as one. */
+export declare class PluginError extends ConfigError {
+    constructor(message: string);
+}
+/** The packages `plugins.json` lists, or none when the file is absent. */
+export declare function listedPlugins(configDir: string): string[];
+/**
+ * Loads the plugins `config/plugins.json` lists, once, at boot (specs/036).
+ * Each is resolved from the tenant project's `node_modules`: by default the
+ * directory that holds `configDir`. Any that does not load is a startup error.
+ *
+ * `SIGHUP` does not come here: it reloads configuration, not code.
+ */
+export declare function loadPlugins(configDir: string, options?: {
+    from?: string;
+}): Promise<Plugins>;

package/dist/plugins/loader.js

@@ -0,0 +1,267 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ConfigError } from "../config/loader.js";
+import { MAX_NOTE_LENGTH } from "../contracts/config.js";
+import { ToolName } from "../contracts/agent.js";
+import { PLUGIN_API_VERSION } from "./api.js";
+import { Plugins } from "./plugins.js";
+/** The optional tenant file that lists the plugin packages to load (specs/036). */
+export const PLUGINS_FILE = 'plugins.json';
+const PluginsFile = z.object({ plugins: z.array(z.string().min(1)) }).strict();
+/** Names the model already knows: the six of specs/012 and the read of specs/024. */
+const BUILT_IN = new Set([...ToolName.options, 'get_contact']);
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const PLUGIN_KEYS = new Set(['name', 'apiVersion', 'tools']);
+const TOOL_KEYS = new Set(['name', 'description', 'parameters', 'perform']);
+const PARAMETER_KEYS = {
+    enum: new Set(['type', 'values', 'description', 'optional']),
+    number: new Set(['type', 'integer', 'min', 'max', 'description', 'optional']),
+    boolean: new Set(['type', 'description', 'optional']),
+    note: new Set(['type', 'maxLength', 'description', 'optional']),
+};
+/** A plugin that cannot be loaded. A `ConfigError`, so every command reports it as one. */
+export class PluginError extends ConfigError {
+    constructor(message) {
+        super(message);
+        this.name = 'PluginError';
+    }
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function unknownKeys(value, allowed) {
+    return Object.keys(value).filter(key => !allowed.has(key));
+}
+/** The directory of `name` in the first `node_modules` above `from`, as Node finds a package. */
+function packageDir(name, from) {
+    let dir = resolve(from);
+    for (;;) {
+        const candidate = join(dir, 'node_modules', name);
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** The ESM entry an `exports` value points the bare import at. */
+function exported(target) {
+    if (typeof target === 'string')
+        return target;
+    if (Array.isArray(target)) {
+        for (const option of target) {
+            const found = exported(option);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (!isObject(target))
+        return undefined;
+    if ('.' in target)
+        return exported(target['.']);
+    for (const condition of ['import', 'node', 'default']) {
+        const found = exported(target[condition]);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function entryOf(dir) {
+    const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    const pkg = isObject(manifest) ? manifest : {};
+    const target = exported(pkg.exports) ?? (typeof pkg.main === 'string' ? pkg.main : undefined) ?? 'index.js';
+    return join(dir, target);
+}
+/**
+ * Checks one parameter against what a built-in tool may take. A string outside
+ * a note is refused, as `tools.json` refuses one (specs/012 § Free-text field
+ * values are refused).
+ */
+function checkParameter(where, key, parameter) {
+    const at = `${where}, parameter "${key}"`;
+    if (!isObject(parameter))
+        throw new PluginError(`${at}: is not a parameter declaration`);
+    const type = parameter.type;
+    if (type === 'string' || type === 'text') {
+        throw new PluginError(`${at}: free text is refused; declare it as a "note" with a maxLength (specs/012)`);
+    }
+    if (typeof type !== 'string' || !(type in PARAMETER_KEYS)) {
+        throw new PluginError(`${at}: type must be one of enum, number, boolean, note`);
+    }
+    const extra = unknownKeys(parameter, PARAMETER_KEYS[type]);
+    if (extra.length > 0)
+        throw new PluginError(`${at}: unknown keys ${extra.join(', ')}`);
+    if (parameter.description !== undefined && typeof parameter.description !== 'string') {
+        throw new PluginError(`${at}: description must be a string`);
+    }
+    if (parameter.optional !== undefined && typeof parameter.optional !== 'boolean') {
+        throw new PluginError(`${at}: optional must be a boolean`);
+    }
+    if (type === 'enum') {
+        const values = parameter.values;
+        if (!Array.isArray(values) ||
+            values.length === 0 ||
+            values.some(value => typeof value !== 'string' || value.length === 0) ||
+            new Set(values).size !== values.length) {
+            throw new PluginError(`${at}: values must be distinct, non-empty strings`);
+        }
+    }
+    if (type === 'number') {
+        const { min, max, integer } = parameter;
+        for (const [name, bound] of [
+            ['min', min],
+            ['max', max],
+        ]) {
+            if (bound !== undefined && (typeof bound !== 'number' || !Number.isFinite(bound))) {
+                throw new PluginError(`${at}: ${name} must be a finite number`);
+            }
+        }
+        if (typeof min === 'number' && typeof max === 'number' && min > max) {
+            throw new PluginError(`${at}: min is greater than max`);
+        }
+        if (integer !== undefined && typeof integer !== 'boolean') {
+            throw new PluginError(`${at}: integer must be a boolean`);
+        }
+    }
+    if (type === 'note') {
+        const { maxLength } = parameter;
+        if (typeof maxLength !== 'number' ||
+            !Number.isInteger(maxLength) ||
+            maxLength < 1 ||
+            maxLength > MAX_NOTE_LENGTH) {
+            throw new PluginError(`${at}: maxLength must be a whole number from 1 to ${MAX_NOTE_LENGTH} (ADR-0017)`);
+        }
+    }
+}
+function checkTool(plugin, value, taken) {
+    if (!isObject(value))
+        throw new PluginError(`plugin ${plugin}: a tool is not an object`);
+    const name = value.name;
+    if (typeof name !== 'string' || !TOOL_NAME.test(name)) {
+        throw new PluginError(`plugin ${plugin}: tool name ${JSON.stringify(name)} must be lowercase snake case`);
+    }
+    const where = `plugin ${plugin}, tool ${name}`;
+    if (BUILT_IN.has(name))
+        throw new PluginError(`${where}: takes the name of a built-in tool`);
+    const owner = taken.get(name);
+    if (owner !== undefined)
+        throw new PluginError(`${where}: plugin ${owner} already defines it`);
+    const extra = unknownKeys(value, TOOL_KEYS);
+    if (extra.length > 0)
+        throw new PluginError(`${where}: unknown keys ${extra.join(', ')}`);
+    if (typeof value.description !== 'string' || value.description.trim().length === 0) {
+        throw new PluginError(`${where}: description must be a non-empty string`);
+    }
+    if (!isObject(value.parameters))
+        throw new PluginError(`${where}: parameters must be an object`);
+    for (const [key, parameter] of Object.entries(value.parameters)) {
+        checkParameter(where, key, parameter);
+    }
+    if (typeof value.perform !== 'function') {
+        throw new PluginError(`${where}: perform must be a function`);
+    }
+    taken.set(name, plugin);
+    return value;
+}
+/**
+ * Checks a plugin's default export. Everything that would leave the prompt
+ * promising an action nothing performs fails here, at startup (C6).
+ */
+function checkPlugin(spec, value, taken) {
+    if (!isObject(value)) {
+        throw new PluginError(`plugin ${spec}: its default export is not a plugin (use definePlugin)`);
+    }
+    if (typeof value.name !== 'string' || value.name.length === 0) {
+        throw new PluginError(`plugin ${spec}: name must be a non-empty string`);
+    }
+    const name = value.name;
+    if (value.apiVersion !== PLUGIN_API_VERSION) {
+        throw new PluginError(`plugin ${name}: apiVersion ${JSON.stringify(value.apiVersion)} is not supported; ` +
+            `this agent supports ${PLUGIN_API_VERSION}`);
+    }
+    // Refused rather than ignored: a channel that silently never mounts is a
+    // contact nobody answers (specs/038).
+    if ('channels' in value) {
+        throw new PluginError(`plugin ${name}: channels are not supported yet (specs/038)`);
+    }
+    const extra = unknownKeys(value, PLUGIN_KEYS);
+    if (extra.length > 0)
+        throw new PluginError(`plugin ${name}: unknown keys ${extra.join(', ')}`);
+    if (value.tools !== undefined && !Array.isArray(value.tools)) {
+        throw new PluginError(`plugin ${name}: tools must be an array`);
+    }
+    const tools = (value.tools ?? []).map(tool => checkTool(name, tool, taken));
+    return { name, tools };
+}
+/** The packages `plugins.json` lists, or none when the file is absent. */
+export function listedPlugins(configDir) {
+    const path = join(configDir, PLUGINS_FILE);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new PluginError(`${PLUGINS_FILE}: ${error.message}`);
+    }
+    const parsed = PluginsFile.safeParse(raw);
+    if (!parsed.success) {
+        throw new PluginError(`${PLUGINS_FILE}: ${z.prettifyError(parsed.error)}`);
+    }
+    const packages = parsed.data.plugins;
+    const repeated = packages.find((name, index) => packages.indexOf(name) !== index);
+    if (repeated !== undefined) {
+        throw new PluginError(`${PLUGINS_FILE}: ${repeated} is listed twice`);
+    }
+    return packages;
+}
+/**
+ * Loads the plugins `config/plugins.json` lists, once, at boot (specs/036).
+ * Each is resolved from the tenant project's `node_modules`: by default the
+ * directory that holds `configDir`. Any that does not load is a startup error.
+ *
+ * `SIGHUP` does not come here: it reloads configuration, not code.
+ */
+export async function loadPlugins(configDir, options = {}) {
+    const packages = listedPlugins(configDir);
+    if (packages.length === 0)
+        return Plugins.NONE;
+    const from = options.from ?? dirname(resolve(configDir));
+    const taken = new Map();
+    const names = new Set();
+    const loaded = [];
+    for (const spec of packages) {
+        if (spec.startsWith('.') || spec.startsWith('/') || spec.includes('\\')) {
+            throw new PluginError(`plugin ${spec}: list a package name, not a path`);
+        }
+        const dir = packageDir(spec, from);
+        if (!dir) {
+            throw new PluginError(`plugin ${spec} is not installed (no node_modules/${spec} from ${from})`);
+        }
+        let module;
+        try {
+            module = (await import(__rewriteRelativeImportExtension(pathToFileURL(entryOf(dir)).href)));
+        }
+        catch (error) {
+            throw new PluginError(`plugin ${spec} failed to load: ${error.message}`);
+        }
+        const plugin = checkPlugin(spec, module.default, taken);
+        if (names.has(plugin.name)) {
+            throw new PluginError(`plugin ${spec}: another plugin is already named ${plugin.name}`);
+        }
+        names.add(plugin.name);
+        loaded.push(...plugin.tools.map(tool => ({ plugin: plugin.name, tool })));
+    }
+    return new Plugins(loaded, [...names]);
+}

package/dist/plugins/plugins.d.ts

@@ -0,0 +1,49 @@
+import { type ToolSet } from 'ai';
+import type { ActionPerformer } from '../channels/manychat/client.ts';
+import type { ActionStage } from '../agent/tools.ts';
+import type { PluginTool } from './api.ts';
+/**
+ * How long the agent waits for a plugin's `perform`. Past it the signal
+ * aborts and the action is recorded as failed, so a hung plugin cannot hold
+ * up the rest of the turn's actions or the outbox (specs/036). Chosen, not
+ * measured: the ManyChat client's own request timeout is shorter.
+ */
+export declare const PLUGIN_PERFORM_TIMEOUT_MS = 10000;
+/** The parameter values a staged plugin action carries, already validated and cleaned. */
+export type PluginParams = Record<string, string | number | boolean>;
+/** The logger the agent writes through; the process's redacting pino logger in production. */
+export interface HostLogger {
+    info: (obj: object, msg: string) => void;
+    warn: (obj: object, msg: string) => void;
+    error: (obj: object, msg: string) => void;
+}
+export interface LoadedTool {
+    /** The plugin that declared it. */
+    plugin: string;
+    tool: PluginTool;
+}
+/**
+ * The plugins a process loaded at boot (specs/036). Each tool is offered to
+ * the model beside the built-in ones and performed after the reply, as a
+ * built-in tool is.
+ */
+export declare class Plugins {
+    static readonly NONE: Plugins;
+    private readonly byName;
+    /** The loaded plugins' names, in the order `plugins.json` lists them. */
+    readonly names: readonly string[];
+    constructor(tools: readonly LoadedTool[], names?: readonly string[]);
+    get hasTools(): boolean;
+    /**
+     * Adds each plugin tool to the turn's tools. A call stages the action and
+     * nothing else; `closed` refuses it as the built-in writes are refused
+     * before a contact is a prospect (specs/034).
+     */
+    addTools(tools: ToolSet, stage: ActionStage, closed: () => boolean, describe: (description: string) => string): void;
+    /**
+     * Wraps the process's performer: a plugin action goes to its plugin, every
+     * other action where it went before.
+     */
+    performer(inner: ActionPerformer, logger: HostLogger): ActionPerformer;
+    private perform;
+}

package/dist/plugins/plugins.js

@@ -0,0 +1,157 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { cleanNote } from "../agent/contact.js";
+import { redactText } from "../observability/redact.js";
+/**
+ * How long the agent waits for a plugin's `perform`. Past it the signal
+ * aborts and the action is recorded as failed, so a hung plugin cannot hold
+ * up the rest of the turn's actions or the outbox (specs/036). Chosen, not
+ * measured: the ManyChat client's own request timeout is shorter.
+ */
+export const PLUGIN_PERFORM_TIMEOUT_MS = 10_000;
+/** The model-facing schema, built here from the declaration, never taken from the plugin. */
+function schemaOf(parameter) {
+    let schema;
+    switch (parameter.type) {
+        case 'enum':
+            schema = z.enum(parameter.values);
+            break;
+        case 'number': {
+            let number = parameter.integer ? z.number().int() : z.number();
+            if (parameter.min !== undefined)
+                number = number.min(parameter.min);
+            if (parameter.max !== undefined)
+                number = number.max(parameter.max);
+            schema = number;
+            break;
+        }
+        case 'boolean':
+            schema = z.boolean();
+            break;
+        case 'note':
+            schema = z.string();
+            break;
+    }
+    if (parameter.description !== undefined)
+        schema = schema.describe(parameter.description);
+    return parameter.optional ? schema.optional() : schema;
+}
+const NOTE_RULE = 'A note parameter is for the people who follow up: never put a name, phone number, email or link in one; they are removed.';
+/**
+ * A logger that redacts what a plugin writes and names the plugin on every
+ * line: the agent's logger, never one the plugin brings (C5).
+ */
+function pluginLogger(host, plugin, subscriberId) {
+    const clean = (text) => redactText(text.split(subscriberId).join('[subscriber]'));
+    const write = (level) => (message, fields = {}) => {
+        const redacted = Object.fromEntries(Object.entries(fields).map(([key, value]) => [
+            key,
+            typeof value === 'string' ? clean(value) : value,
+        ]));
+        host[level]({ ...redacted, plugin }, clean(message));
+    };
+    return { info: write('info'), warn: write('warn'), error: write('error') };
+}
+/**
+ * The plugins a process loaded at boot (specs/036). Each tool is offered to
+ * the model beside the built-in ones and performed after the reply, as a
+ * built-in tool is.
+ */
+export class Plugins {
+    static NONE = new Plugins([]);
+    byName;
+    /** The loaded plugins' names, in the order `plugins.json` lists them. */
+    names;
+    constructor(tools, names = []) {
+        this.byName = new Map(tools.map(entry => [entry.tool.name, entry]));
+        this.names = names;
+    }
+    get hasTools() {
+        return this.byName.size > 0;
+    }
+    /**
+     * Adds each plugin tool to the turn's tools. A call stages the action and
+     * nothing else; `closed` refuses it as the built-in writes are refused
+     * before a contact is a prospect (specs/034).
+     */
+    addTools(tools, stage, closed, describe) {
+        for (const { plugin, tool: declared } of this.byName.values()) {
+            const parameters = Object.entries(declared.parameters);
+            const notes = parameters.filter(([, parameter]) => parameter.type === 'note');
+            tools[declared.name] = tool({
+                description: describe(notes.length > 0 ? `${declared.description}\n${NOTE_RULE}` : declared.description),
+                inputSchema: z.object(Object.fromEntries(parameters.map(([key, parameter]) => [key, schemaOf(parameter)]))),
+                execute: (input) => {
+                    if (closed())
+                        return { staged: false, reason: 'not_prospect' };
+                    const params = {};
+                    const notes = {};
+                    for (const [key, parameter] of parameters) {
+                        const value = input[key];
+                        if (value === undefined)
+                            continue;
+                        if (parameter.type !== 'note') {
+                            params[key] = value;
+                            continue;
+                        }
+                        // Cleaned when staged, as a `tools.json` note is, so the outbox
+                        // never holds what the plugin will not be given (specs/024).
+                        const cleaned = cleanNote(value, parameter.maxLength);
+                        if (cleaned.length > 0)
+                            notes[key] = cleaned;
+                        else if (!parameter.optional)
+                            return { staged: false };
+                    }
+                    return {
+                        staged: stage.stage({
+                            tool: 'plugin',
+                            id: declared.name,
+                            plugin,
+                            params,
+                            ...(Object.keys(notes).length > 0 ? { notes } : {}),
+                        }),
+                    };
+                },
+            });
+        }
+    }
+    /**
+     * Wraps the process's performer: a plugin action goes to its plugin, every
+     * other action where it went before.
+     */
+    performer(inner, logger) {
+        return {
+            performAction: (subscriberId, action) => action.tool === 'plugin'
+                ? this.perform(subscriberId, action.id, { ...action.params, ...action.notes }, logger)
+                : inner.performAction(subscriberId, action),
+        };
+    }
+    async perform(subscriberId, name, params, logger) {
+        // A row queued before a restart that dropped the plugin.
+        const entry = this.byName.get(name);
+        if (!entry)
+            throw new Error(`plugin tool ${name} is not loaded`);
+        const controller = new AbortController();
+        let timer;
+        const timedOut = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error(`plugin tool ${name} timed out after ${PLUGIN_PERFORM_TIMEOUT_MS} ms`));
+            }, PLUGIN_PERFORM_TIMEOUT_MS);
+        });
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => entry.tool.perform({
+                    subscriberId,
+                    params,
+                    logger: pluginLogger(logger, entry.plugin, subscriberId),
+                    signal: controller.signal,
+                })),
+                timedOut,
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/server.d.ts

@@ -7,6 +7,7 @@ import type { AgentRunner } from './agent/runner.ts';
 import type { ContactReader, ManyChatClient } from './channels/manychat/client.ts';
 import type { ConfigStore } from './config/loader.ts';
 import { type FfmpegPaths } from './media/ffmpeg.ts';
+import { Plugins } from './plugins/plugins.ts';
 export interface BuildOptions {
     env: Env;
     db: Database;
@@ -34,6 +35,8 @@ export interface BuildOptions {
     transcriptionModel?: TranscriptionModel;
     /** Injected by tests to stand in for a server without ffmpeg. */
     ffmpegPaths?: FfmpegPaths;
+    /** The tenant's plugins, loaded once at boot (specs/036). None when absent. */
+    plugins?: Plugins;
 }
 /**
  * The whole production composition. Plugins are registered before any route is

package/dist/server.js

@@ -20,6 +20,7 @@ import { bearerToken, createSharedSecretGuard, isAuthenticated } from "./routes/
 import { escalationReply } from "./agent/guardrails.js";
 import { mediaScrubbingStream, redactText } from "./observability/redact.js";
 import { loggerOptions } from "./observability/logger.js";
+import { Plugins } from "./plugins/plugins.js";
 const MESSAGE_ROUTE = '/v1/channels/manychat/message';
 /**
  * The whole production composition. Plugins are registered before any route is
@@ -52,6 +53,7 @@ export async function buildServer(opts) {
     const manychatClient = opts.manychat ?? built;
     const contacts = opts.contacts ?? built;
     const adapter = new ManyChatAdapter(manychatClient);
+    const plugins = opts.plugins ?? Plugins.NONE;
     const runner = opts.runner ??
         new GenerateTextRunner({
             model: resolveModel(env.AGENT_MODEL),
@@ -62,6 +64,7 @@ export async function buildServer(opts) {
             maxOutputTokens: env.AGENT_MAX_OUTPUT_TOKENS,
             temperature: env.AGENT_TEMPERATURE,
             reasoningEffort: env.AGENT_REASONING_EFFORT,
+            plugins,
         });
     // Resolved once, like the answering model: a TRANSCRIPTION_MODEL typo fails
     // the deploy, and a missing ffmpeg is found at boot rather than per video.
@@ -210,7 +213,8 @@ export async function buildServer(opts) {
             logger: request.log,
             tokenWriter: manychatClient,
             tokensEnforced: env.CONTACT_TOKENS_ENFORCED,
-            actions: manychatClient,
+            // A plugin action goes to its plugin, the rest to ManyChat (specs/036).
+            actions: plugins.performer(manychatClient, request.log),
             contacts,
             media,
             lanes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "manychat-ai-agent",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "A provider-agnostic conversational AI agent gateway that bridges no-code chat platforms to any LLM.",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,10 @@
     "agent": "dist/cli.js"
   },
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./config": {
       "types": "./dist/config/index.d.ts",
       "default": "./dist/config/index.js"