manychat-ai-agent 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.23.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.22.0...v0.23.0) (2026-10-08)
+
+
+### Features
+
+* mount plugin channels beside ManyChat's route (spec 038) ([366c646](https://github.com/pedronastasi/manychat-ai-agent/commit/366c646a7223d959603b0f6f5159725d368bf33c))
+* mount plugin channels beside ManyChat's route (spec 038) ([e53d5ed](https://github.com/pedronastasi/manychat-ai-agent/commit/e53d5ed9ea667246d4788faa087226049350ab96))
+
+
+### Specs and Docs
+
+* record PR 206 in spec 038 ([f61a13e](https://github.com/pedronastasi/manychat-ai-agent/commit/f61a13ea2448920db388d842da52bfb7a655a698))
+
 ## [0.22.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.21.0...v0.22.0) (2026-10-08)
 
 

package/dist/agent/runner.d.ts

@@ -109,6 +109,12 @@ export interface AgentTurnInput {
     nudge?: {
         since: Date;
     } | undefined;
+    /**
+     * False on a plugin channel's turn: `tools.json`'s tools write to ManyChat,
+     * so neither they nor their prompt lines are offered there. Plugin tools
+     * still are (specs/038).
+     */
+    builtInTools?: boolean | undefined;
 }
 /**
  * The port every caller depends on. Implemented with `generateText`: a single
@@ -150,7 +156,8 @@ export interface RunnerOptions {
 }
 export declare class GenerateTextRunner implements AgentRunner {
     private readonly opts;
-    private cached;
+    /** One per kind of turn: with `tools.json`'s tools, and without them (specs/038). */
+    private readonly cached;
     constructor(opts: RunnerOptions);
     /**
      * Rebuilds only when ConfigStore swaps in a new object, so the prefix stays
@@ -159,5 +166,5 @@ export declare class GenerateTextRunner implements AgentRunner {
      * An activated playbook version rebuilds it once, not on every turn.
      */
     private current;
-    run({ text, history, signal, media, stage, contact, reads, pluginReads, flows, beforeFlow, nudge, }: AgentTurnInput): Promise<AgentResult>;
+    run({ text, history, signal, media, stage, contact, reads, pluginReads, flows, beforeFlow, nudge, builtInTools, }: AgentTurnInput): Promise<AgentResult>;
 }

package/dist/agent/runner.js

@@ -79,7 +79,8 @@ function nudgeMessage(since, contactNotices) {
 }
 export class GenerateTextRunner {
     opts;
-    cached;
+    /** One per kind of turn: with `tools.json`'s tools, and without them (specs/038). */
+    cached = new Map();
     constructor(opts) {
         this.opts = opts;
     }
@@ -89,43 +90,46 @@ export class GenerateTextRunner {
      * failed reload keeps the previous object, so it correctly rebuilds nothing.
      * An activated playbook version rebuilds it once, not on every turn.
      */
-    current() {
+    current(builtInTools) {
         const config = this.opts.config();
         const playbook = this.opts.playbook?.current();
-        if (this.cached?.config !== config || this.cached.loadedPlaybook !== playbook?.id) {
-            const tools = config.tools ?? NO_TOOLS;
-            // The staged-tool lines follow write tools only: a read is not staged
-            // (specs/039 § The prompt changes only when a plugin adds a read tool).
-            const pluginTools = this.opts.plugins?.hasWriteTools ?? false;
-            const pluginReadTools = this.opts.plugins?.hasReadTools ?? false;
-            const withTools = offersTools(tools) || pluginTools || pluginReadTools;
-            const prompt = buildSystemPrompt(config.persona, config.catalog, config.rules, tools, {
-                pluginTools,
-                pluginReadTools,
-            });
-            // After the catalog and before the cache breakpoint, so a version is
-            // cached with the rest of the prefix (specs/031). Without `learning`
-            // the prefix is what it was before that spec.
-            const rendered = config.rules.learning ? renderPlaybook(playbook) : undefined;
-            this.cached = {
-                config,
-                loadedPlaybook: playbook?.id,
-                playbook: rendered ? playbook : undefined,
-                withTools,
-                staticPrefix: prompt.staticPrefix,
-                catalogBlock: rendered ? `${prompt.catalogBlock}\n\n${rendered}` : prompt.catalogBlock,
-            };
-        }
-        return this.cached;
+        const cached = this.cached.get(builtInTools);
+        if (cached?.config === config && cached.loadedPlaybook === playbook?.id)
+            return cached;
+        const tools = builtInTools ? (config.tools ?? NO_TOOLS) : NO_TOOLS;
+        // The staged-tool lines follow write tools only: a read is not staged
+        // (specs/039 § The prompt changes only when a plugin adds a read tool).
+        const pluginTools = this.opts.plugins?.hasWriteTools ?? false;
+        const pluginReadTools = this.opts.plugins?.hasReadTools ?? false;
+        const withTools = offersTools(tools) || pluginTools || pluginReadTools;
+        const prompt = buildSystemPrompt(config.persona, config.catalog, config.rules, tools, {
+            pluginTools,
+            pluginReadTools,
+        });
+        // After the catalog and before the cache breakpoint, so a version is
+        // cached with the rest of the prefix (specs/031). Without `learning`
+        // the prefix is what it was before that spec.
+        const rendered = config.rules.learning ? renderPlaybook(playbook) : undefined;
+        const built = {
+            config,
+            loadedPlaybook: playbook?.id,
+            playbook: rendered ? playbook : undefined,
+            withTools,
+            tools,
+            staticPrefix: prompt.staticPrefix,
+            catalogBlock: rendered ? `${prompt.catalogBlock}\n\n${rendered}` : prompt.catalogBlock,
+        };
+        this.cached.set(builtInTools, built);
+        return built;
     }
-    async run({ text, history, signal, media, stage = new ActionStage(), contact, reads, pluginReads, flows, beforeFlow, nudge, }) {
+    async run({ text, history, signal, media, stage = new ActionStage(), contact, reads, pluginReads, flows, beforeFlow, nudge, builtInTools = true, }) {
         const started = Date.now();
         // Resolved once per turn: a reload landing mid-turn must not produce a
         // reply built from one config and guarded by another.
-        const { config, playbook, staticPrefix, catalogBlock, withTools } = this.current();
+        const { config, playbook, staticPrefix, catalogBlock, withTools, tools: tenantTools, } = this.current(builtInTools);
         const playbookVersion = playbook?.id ?? null;
         const tools = withTools
-            ? buildTools(config.tools ?? NO_TOOLS, stage, contact, reads, {
+            ? buildTools(tenantTools, stage, contact, reads, {
                 nudgeTurn: nudge !== undefined,
                 flows,
                 beforeFlow,
@@ -135,13 +139,11 @@ export class GenerateTextRunner {
             : undefined;
         // The opening is no longer known before the loop runs: the prospect write
         // that queues it says so, and the reply step is told below (specs/034).
-        const opening = contact?.openingDue ? openingFlow(config.tools ?? NO_TOOLS) : undefined;
+        const opening = contact?.openingDue ? openingFlow(tenantTools) : undefined;
         const contactNotices = [
-            ...(intentField(config.tools ?? NO_TOOLS)
-                ? [intentNotice(contact?.intent, contact?.advertOffering)]
-                : []),
-            ...(funnelField(config.tools ?? NO_TOOLS) ? [funnelNotice(contact?.funnelStage)] : []),
-            ...(offeringField(config.tools ?? NO_TOOLS)
+            ...(intentField(tenantTools) ? [intentNotice(contact?.intent, contact?.advertOffering)] : []),
+            ...(funnelField(tenantTools) ? [funnelNotice(contact?.funnelStage)] : []),
+            ...(offeringField(tenantTools)
                 ? [offeringNotice(contact?.offering, contact?.offeringChangedFrom)]
                 : []),
         ];
@@ -167,9 +169,7 @@ export class GenerateTextRunner {
                             ...messages,
                             {
                                 role: 'user',
-                                content: stagedNotice(stage, reads?.latest, opening && stagesProspect(stage, config.tools ?? NO_TOOLS)
-                                    ? opening
-                                    : undefined, pluginReads?.latest),
+                                content: stagedNotice(stage, reads?.latest, opening && stagesProspect(stage, tenantTools) ? opening : undefined, pluginReads?.latest),
                             },
                         ],
                     }

package/dist/channels/plugin/adapter.d.ts

@@ -0,0 +1,47 @@
+import { type AgentReply, type InboundMessage } from '../../contracts/agent.ts';
+import type { ChannelReply, PluginChannel } from '../../plugins/api.ts';
+import { type HostLogger, type Plugins } from '../../plugins/plugins.ts';
+import type { ChannelAdapter, ParseContext } from '../port.ts';
+/**
+ * How long the outbox waits for a channel's `push`. Past it the signal aborts
+ * and the delivery is retried, as a ManyChat send that timed out is. The same
+ * bound as a plugin's `perform` (specs/036); chosen, not measured.
+ */
+export declare const CHANNEL_PUSH_TIMEOUT_MS = 10000;
+/** A request that fails the channel's own schema: refused with a 400 before any turn (specs/038). */
+export declare class ChannelInputError extends Error {
+    constructor(channel: string);
+}
+/** The route a channel is mounted at, beside ManyChat's (specs/038). */
+export declare const channelRoute: (name: string) => string;
+/**
+ * A plugin's channel behind the `ChannelAdapter` port (specs/038, ADR-0005).
+ * The plugin translates; everything it does not translate is decided here,
+ * the same way for every plugin channel: the tenant, the channel, and that
+ * the request carries no contact token and no offering.
+ *
+ * The contact's ID is prefixed with the channel's name, so a contact on one
+ * channel never shares a conversation, an order or an outbox lane with one on
+ * another whose platform happens to use the same ID.
+ */
+export declare class PluginChannelAdapter implements ChannelAdapter<unknown, unknown> {
+    readonly name: string;
+    readonly plugin: string;
+    readonly route: string;
+    private readonly channel;
+    private readonly logger;
+    private readonly prefix;
+    constructor(plugin: string, channel: PluginChannel, logger: HostLogger);
+    /** Whether the request passes the channel's schema; checked before anything reads it (C3). */
+    accepts(raw: unknown): boolean;
+    parse(raw: unknown, ctx: ParseContext): InboundMessage;
+    render(reply: AgentReply): unknown;
+    /** Delivers a lost race's reply (specs/038 § Outbound delivery is the adapter's `push`). */
+    push(to: {
+        subscriberId: string;
+    }, reply: AgentReply): Promise<void>;
+    /** What `push` sends, from what the outbox keeps of a reply. */
+    deliver(to: string, reply: ChannelReply): Promise<void>;
+}
+/** An adapter for each channel the plugins add, by name, logging through `logger`. */
+export declare function channelAdapters(plugins: Plugins, logger: HostLogger): ReadonlyMap<string, PluginChannelAdapter>;

package/dist/channels/plugin/adapter.js

@@ -0,0 +1,108 @@
+import { ChannelMessage } from "../../contracts/agent.js";
+import { pluginLogger } from "../../plugins/plugins.js";
+/**
+ * How long the outbox waits for a channel's `push`. Past it the signal aborts
+ * and the delivery is retried, as a ManyChat send that timed out is. The same
+ * bound as a plugin's `perform` (specs/036); chosen, not measured.
+ */
+export const CHANNEL_PUSH_TIMEOUT_MS = 10_000;
+/** A request that fails the channel's own schema: refused with a 400 before any turn (specs/038). */
+export class ChannelInputError extends Error {
+    constructor(channel) {
+        super(`request does not match channel ${channel}'s schema`);
+        this.name = 'ChannelInputError';
+    }
+}
+/** The route a channel is mounted at, beside ManyChat's (specs/038). */
+export const channelRoute = (name) => `/v1/channels/${name}/message`;
+/**
+ * A plugin's channel behind the `ChannelAdapter` port (specs/038, ADR-0005).
+ * The plugin translates; everything it does not translate is decided here,
+ * the same way for every plugin channel: the tenant, the channel, and that
+ * the request carries no contact token and no offering.
+ *
+ * The contact's ID is prefixed with the channel's name, so a contact on one
+ * channel never shares a conversation, an order or an outbox lane with one on
+ * another whose platform happens to use the same ID.
+ */
+export class PluginChannelAdapter {
+    name;
+    plugin;
+    route;
+    channel;
+    logger;
+    prefix;
+    constructor(plugin, channel, logger) {
+        this.plugin = plugin;
+        this.channel = channel;
+        this.logger = logger;
+        this.name = channel.name;
+        this.route = channelRoute(channel.name);
+        this.prefix = `${channel.name}:`;
+    }
+    /** Whether the request passes the channel's schema; checked before anything reads it (C3). */
+    accepts(raw) {
+        return this.channel.inbound.safeParse(raw).success;
+    }
+    parse(raw, ctx) {
+        const checked = this.channel.inbound.safeParse(raw);
+        if (!checked.success)
+            throw new ChannelInputError(this.name);
+        // What the plugin returns is an external boundary too (C3).
+        const message = ChannelMessage.parse(this.channel.parse(checked.data));
+        return {
+            tenantId: ctx.tenantId,
+            subscriberId: `${this.prefix}${message.subscriberId}`,
+            text: message.text,
+            channel: this.name,
+            contactName: message.contactName ?? null,
+            locale: message.locale ?? null,
+            // The channel's own auth binds its contacts: there is no token to
+            // present, and none is issued (specs/038 § A plugin channel carries no
+            // contact token).
+            contactToken: null,
+            offering: null,
+            receivedAt: new Date(),
+        };
+    }
+    render(reply) {
+        return this.channel.render({ messages: reply.messages, escalate: reply.escalate });
+    }
+    /** Delivers a lost race's reply (specs/038 § Outbound delivery is the adapter's `push`). */
+    async push(to, reply) {
+        await this.deliver(to.subscriberId, { messages: reply.messages, escalate: reply.escalate });
+    }
+    /** What `push` sends, from what the outbox keeps of a reply. */
+    async deliver(to, reply) {
+        const subscriberId = to.startsWith(this.prefix) ? to.slice(this.prefix.length) : to;
+        const controller = new AbortController();
+        let timer;
+        const timedOut = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error(`channel ${this.name} push timed out after ${CHANNEL_PUSH_TIMEOUT_MS} ms`));
+            }, CHANNEL_PUSH_TIMEOUT_MS);
+        });
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => this.channel.push({
+                    subscriberId,
+                    reply,
+                    logger: pluginLogger(this.logger, this.plugin, subscriberId),
+                    signal: controller.signal,
+                })),
+                timedOut,
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** An adapter for each channel the plugins add, by name, logging through `logger`. */
+export function channelAdapters(plugins, logger) {
+    return new Map(plugins.channels.map(({ plugin, channel }) => [
+        channel.name,
+        new PluginChannelAdapter(plugin, channel, logger),
+    ]));
+}

package/dist/cli/run.js

@@ -112,11 +112,13 @@ export async function run(argv) {
                 }
                 throw error;
             }
-            // Each plugin's read tools beside its write tools (specs/039).
+            // Each plugin's read tools beside its write tools (specs/039), and its channels.
             const tools = (names) => (names.length > 0 ? names.join(', ') : 'none');
             const loaded = summary.length > 0
                 ? `; plugins: ${summary
-                    .map(entry => `${entry.plugin} (writes: ${tools(entry.writes)}; reads: ${tools(entry.reads)})`)
+                    .map(entry => `${entry.plugin} (writes: ${tools(entry.writes)}; reads: ${tools(entry.reads)}` +
+                    // Only a plugin that adds one says so (specs/038).
+                    (entry.channels.length > 0 ? `; channels: ${entry.channels.join(', ')})` : ')'))
                     .join(', ')}`
                 : '';
             console.log(`config check passed (${configDir}${loaded})`);

package/dist/contracts/agent.d.ts

@@ -114,6 +114,17 @@ export declare const InboundMessage: z.ZodObject<{
     receivedAt: z.ZodDate;
 }, z.core.$strip>;
 export type InboundMessage = z.infer<typeof InboundMessage>;
+/**
+ * What a plugin channel's `parse` returns, checked before the turn reads it
+ * (specs/038, C3). The bounds are ManyChat's inbound ones.
+ */
+export declare const ChannelMessage: z.ZodObject<{
+    subscriberId: z.ZodString;
+    text: z.ZodString;
+    contactName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ChannelMessage = z.infer<typeof ChannelMessage>;
 /** Why a turn ended the way it did — recorded per turn for observability. */
 export declare const TurnOutcome: z.ZodEnum<{
     error: "error";

package/dist/contracts/agent.js

@@ -116,6 +116,18 @@ export const InboundMessage = z.object({
     offering: z.string().nullish(),
     receivedAt: z.date(),
 });
+/**
+ * What a plugin channel's `parse` returns, checked before the turn reads it
+ * (specs/038, C3). The bounds are ManyChat's inbound ones.
+ */
+export const ChannelMessage = z
+    .object({
+    subscriberId: z.string().min(1).max(256),
+    text: z.string().max(4096),
+    contactName: z.string().max(256).nullish(),
+    locale: z.string().max(64).nullish(),
+})
+    .strict();
 /** Why a turn ended the way it did — recorded per turn for observability. */
 export const TurnOutcome = z.enum([
     'answered_inline', // model won the race

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * The bare `manychat-ai-agent` entry point: the plugin API (specs/036, with
- * read tools from specs/039). The agent itself is run through its CLI or
+ * read tools from specs/039 and provisional channels from specs/038). The agent itself is run through its CLI or
  * image, never imported.
  */
-export { definePlugin, defineReadTool, defineTool, PLUGIN_API_VERSION, SUPPORTED_PLUGIN_API_VERSIONS, } from './plugins/api.ts';
-export type { ParamsOf, Plugin, PluginCall, PluginLogger, PluginParameter, PluginParameters, PluginReadTool, PluginTool, ReadParameter, ReadParameters, ResultField, ResultFields, ResultOf, } from './plugins/api.ts';
+export { CHANNEL_API_VERSION, defineChannel, definePlugin, defineReadTool, defineTool, PLUGIN_API_VERSION, SUPPORTED_CHANNEL_API_VERSIONS, SUPPORTED_PLUGIN_API_VERSIONS, } from './plugins/api.ts';
+export type { ChannelMessage, ChannelPush, ChannelReply, InboundSchema, ParamsOf, Plugin, PluginCall, PluginChannel, PluginLogger, PluginParameter, PluginParameters, PluginReadTool, PluginTool, ReadParameter, ReadParameters, ResultField, ResultFields, ResultOf, } from './plugins/api.ts';

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * The bare `manychat-ai-agent` entry point: the plugin API (specs/036, with
- * read tools from specs/039). The agent itself is run through its CLI or
+ * read tools from specs/039 and provisional channels from specs/038). The agent itself is run through its CLI or
  * image, never imported.
  */
-export { definePlugin, defineReadTool, defineTool, PLUGIN_API_VERSION, SUPPORTED_PLUGIN_API_VERSIONS, } from "./plugins/api.js";
+export { CHANNEL_API_VERSION, defineChannel, definePlugin, defineReadTool, defineTool, PLUGIN_API_VERSION, SUPPORTED_CHANNEL_API_VERSIONS, SUPPORTED_PLUGIN_API_VERSIONS, } from "./plugins/api.js";

package/dist/outbox/queue.d.ts

@@ -15,6 +15,10 @@ export interface ReplyPayload {
     messages: string[];
     actions?: StagedAction[];
     turnId?: string;
+    /** The plugin channel that delivers it, through its adapter's `push`; ManyChat when absent (specs/038). */
+    channel?: string;
+    /** Set on a handoff queued for a plugin channel, which is told so (specs/038). */
+    escalate?: true;
 }
 /**
  * A deferred reply, or the retry of a contact token's write (specs/019). The
@@ -45,6 +49,8 @@ export declare class OutboxQueue {
         } | undefined;
         /** Held until then: a flow sent this turn is still playing (specs/030). */
         notBefore?: Date | undefined;
+        /** A plugin channel's name; ManyChat when absent (specs/038). */
+        channel?: string | undefined;
     }): Promise<string>;
     /**
      * Whether a reply to the contact is still queued: pending, or being

package/dist/outbox/queue.js

@@ -8,6 +8,11 @@ export class OutboxQueue {
     }
     async enqueue(input) {
         const payload = { messages: input.reply.messages };
+        if (input.channel !== undefined) {
+            payload.channel = input.channel;
+            if (input.reply.escalate)
+                payload.escalate = true;
+        }
         if (input.actions && input.actions.staged.length > 0) {
             payload.actions = [...input.actions.staged];
             payload.turnId = input.actions.turnId;

package/dist/outbox/worker.d.ts

@@ -1,6 +1,13 @@
 import type { Database } from '../db/client.ts';
 import type { ManyChatClient } from '../channels/manychat/client.ts';
 import type { Plugins } from '../plugins/plugins.ts';
+/**
+ * A reply queued for a channel no plugin adds any more, because the process
+ * restarted without it. Never retried and never sent to ManyChat (specs/038).
+ */
+export declare class ChannelNotLoadedError extends Error {
+    constructor(channel: string);
+}
 export interface WorkerLogger {
     info: (obj: object, msg: string) => void;
     warn: (obj: object, msg: string) => void;
@@ -30,6 +37,8 @@ export declare class OutboxWorker {
     private readonly store;
     private readonly nudges;
     private readonly actions;
+    /** The plugins' channels, which deliver their own replies (specs/038). */
+    private readonly channels;
     private running;
     /**
      * Set by the stop function. A contact's rows after the one being sent go

package/dist/outbox/worker.js

@@ -6,6 +6,17 @@ import { performActions, performedOffering } from "../conversation/actions.js";
 import { recordOf } from "../agent/tools.js";
 import { NudgeStore } from "../nudge/store.js";
 import { NudgingPerformer } from "../nudge/performer.js";
+import { channelAdapters } from "../channels/plugin/adapter.js";
+/**
+ * A reply queued for a channel no plugin adds any more, because the process
+ * restarted without it. Never retried and never sent to ManyChat (specs/038).
+ */
+export class ChannelNotLoadedError extends Error {
+    constructor(channel) {
+        super(`channel ${channel} is not loaded`);
+        this.name = 'ChannelNotLoadedError';
+    }
+}
 export class OutboxWorker {
     opts;
     queue;
@@ -13,6 +24,8 @@ export class OutboxWorker {
     store;
     nudges;
     actions;
+    /** The plugins' channels, which deliver their own replies (specs/038). */
+    channels;
     running = false;
     /**
      * Set by the stop function. A contact's rows after the one being sent go
@@ -28,6 +41,7 @@ export class OutboxWorker {
         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;
+        this.channels = opts.plugins ? channelAdapters(opts.plugins, opts.logger) : new Map();
     }
     /**
      * The actions deferred with a reply, performed once, after its first
@@ -69,7 +83,17 @@ export class OutboxWorker {
     }
     async deliver(row) {
         if (row.kind === 'reply') {
-            await this.opts.client.sendText(row.subscriberId, row.payload.messages);
+            const { channel, messages, escalate } = row.payload;
+            if (channel === undefined) {
+                await this.opts.client.sendText(row.subscriberId, messages);
+                return;
+            }
+            // A plugin channel's reply goes out through its own adapter, never
+            // through ManyChat (specs/038).
+            const adapter = this.channels.get(channel);
+            if (!adapter)
+                throw new ChannelNotLoadedError(channel);
+            await adapter.deliver(row.subscriberId, { messages, escalate: escalate === true });
             return;
         }
         // The token that failed to land was never stored, so a fresh one replaces
@@ -140,7 +164,10 @@ export class OutboxWorker {
             // ManyChat's own verdict when it is ManyChat's error, and a retry
             // otherwise: an unknown failure, such as the database, must not
             // discard a reply (specs/022 § Retries follow the SDK's retryable).
-            const retryable = error instanceof ManyChatError ? error.retryable : true;
+            const retryable = error instanceof ManyChatError
+                ? error.retryable
+                : // A channel that is gone will not come back by retrying (specs/038).
+                    !(error instanceof ChannelNotLoadedError);
             // A token write's error is kept to its status: ManyChat's answer to it
             // could quote the value it was sent (specs/019).
             const message = row.kind === 'contact_token'

package/dist/plugins/api.d.ts

@@ -2,7 +2,7 @@
  * 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. A write tool is staged when the model calls it and
+ * A plugin adds tools, and channels (specs/038). A write tool is staged when the model calls it and
  * performed after the reply, exactly as the built-in tools of specs/012 are.
  * A read tool is performed when called, as `get_contact` is, and the model is
  * shown only the result it declares (specs/039). Neither gets more power than
@@ -186,11 +186,88 @@ export interface PluginReadTool<S extends ReadParameters = ReadParameters, R ext
      */
     read(call: PluginCall<ParamsOf<S>>): Promise<ResultOf<R>> | ResultOf<R>;
 }
+/**
+ * The newest channel API this agent implements (specs/038). Provisional: it
+ * may break in any minor release until a second adapter has been built
+ * against it, which is why it is `0` and versioned apart from the tool API.
+ */
+export declare const CHANNEL_API_VERSION = 0;
+/** Every channel `apiVersion` this agent mounts. A channel naming another is refused at startup. */
+export declare const SUPPORTED_CHANNEL_API_VERSIONS: readonly number[];
+/**
+ * The schema a channel validates its inbound request with (C3): a Zod
+ * schema, or anything with the same `safeParse`.
+ */
+export interface InboundSchema<T> {
+    safeParse(raw: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+/**
+ * What a channel's `parse` translates its request into. The agent fills in the
+ * rest: the tenant, the channel, and that the request carries no contact token
+ * and no offering (specs/038 § The adapter translates, and decides nothing).
+ */
+export interface ChannelMessage {
+    /** The contact's ID on the platform. The agent prefixes it with the channel's name. */
+    subscriberId: string;
+    text: string;
+    contactName?: string | null | undefined;
+    locale?: string | null | undefined;
+}
+/** What a channel renders or pushes: the reply's messages, and whether it hands off to a person. */
+export interface ChannelReply {
+    /**
+     * Empty when rendered for a response that says nothing yet: the contact's
+     * previous reply is still queued, and this one follows through `push`
+     * (specs/037).
+     */
+    messages: readonly string[];
+    escalate: boolean;
+}
+/** Everything `push` is given: the contact's platform ID, the reply, the logger and a signal. */
+export interface ChannelPush {
+    /** The ID `parse` returned, without the channel's prefix. */
+    subscriberId: string;
+    reply: ChannelReply;
+    logger: PluginLogger;
+    signal: AbortSignal;
+}
+/**
+ * A channel other than ManyChat (specs/038): the `ChannelAdapter` port, as a
+ * plugin implements it. Mounted at `/v1/channels/<name>/message` behind the
+ * same auth, budget, race, order and outbox as ManyChat's route.
+ *
+ * Provisional: see `CHANNEL_API_VERSION`.
+ */
+export interface PluginChannel<TInbound = unknown, TOutbound = unknown> {
+    /** Lowercase, digits and dashes; the route's path segment. Not `manychat`. */
+    name: string;
+    /** The channel API it was written against: `0`, provisional. */
+    apiVersion: number;
+    /** Validates the request before anything reads it; one that fails is refused with a 400. */
+    inbound: InboundSchema<TInbound>;
+    /** Translates the validated request. Throwing hands the contact to a person. */
+    parse(request: TInbound): ChannelMessage;
+    /** Renders the reply as the platform's response body. */
+    render(reply: ChannelReply): TOutbound;
+    /**
+     * Delivers a reply outside the request, for a lost race. Throwing retries
+     * it, as the outbox retries ManyChat; past 10 seconds it counts as failed.
+     */
+    push(call: ChannelPush): Promise<void> | void;
+}
 export interface Plugin {
     name: string;
-    /** The plugin API it was written against; a read tool needs `2`. */
+    /** The plugin API its tools were written against; a read tool needs `2`. */
     apiVersion: number;
     tools?: readonly (PluginTool<any> | PluginReadTool<any, any>)[];
+    /** Channels, each with its own provisional `apiVersion` (specs/038). */
+    channels?: readonly PluginChannel<any, any>[];
 }
 /**
  * A plugin package's default export. Returns the plugin unchanged: the agent
@@ -199,6 +276,8 @@ export interface Plugin {
 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>;
+/** Types a channel's `parse` from its inbound schema. Returns the channel unchanged. */
+export declare function defineChannel<TInbound, TOutbound>(channel: PluginChannel<TInbound, TOutbound>): PluginChannel<TInbound, TOutbound>;
 /** Types a read tool's `read` from its parameters and result. Returns the tool unchanged. */
 export declare function defineReadTool<const S extends ReadParameters, const R extends ResultFields>(tool: PluginReadTool<S, R>): PluginReadTool<S, R>;
 export {};

package/dist/plugins/api.js

@@ -2,7 +2,7 @@
  * 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. A write tool is staged when the model calls it and
+ * A plugin adds tools, and channels (specs/038). A write tool is staged when the model calls it and
  * performed after the reply, exactly as the built-in tools of specs/012 are.
  * A read tool is performed when called, as `get_contact` is, and the model is
  * shown only the result it declares (specs/039). Neither gets more power than
@@ -20,6 +20,14 @@ export const MAX_RESULT_TEXT_LENGTH = 1000;
 export const MAX_RESULT_ITEMS = 5;
 /** The longest a read result may be once serialised. Chosen, not measured. */
 export const MAX_RESULT_LENGTH = 2000;
+/**
+ * The newest channel API this agent implements (specs/038). Provisional: it
+ * may break in any minor release until a second adapter has been built
+ * against it, which is why it is `0` and versioned apart from the tool API.
+ */
+export const CHANNEL_API_VERSION = 0;
+/** Every channel `apiVersion` this agent mounts. A channel naming another is refused at startup. */
+export const SUPPORTED_CHANNEL_API_VERSIONS = [0];
 /**
  * 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.
@@ -31,6 +39,10 @@ export function definePlugin(plugin) {
 export function defineTool(tool) {
     return tool;
 }
+/** Types a channel's `parse` from its inbound schema. Returns the channel unchanged. */
+export function defineChannel(channel) {
+    return channel;
+}
 /** Types a read tool's `read` from its parameters and result. Returns the tool unchanged. */
 export function defineReadTool(tool) {
     return tool;

package/dist/plugins/loader.d.ts

@@ -1,5 +1,5 @@
 import { ConfigError } from '../config/loader.ts';
-import type { PluginReadTool, PluginTool } from './api.ts';
+import type { PluginChannel, PluginReadTool, PluginTool } from './api.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";
@@ -7,6 +7,10 @@ export declare const PLUGINS_FILE = "plugins.json";
 export declare const BUILT_IN_TOOLS: ReadonlySet<string>;
 /** A tool name the loader accepts: lowercase snake case, at most 64 characters. */
 export declare const TOOL_NAME: RegExp;
+/** A channel name the loader accepts: the path segment of its route (specs/038). */
+export declare const CHANNEL_NAME: RegExp;
+/** Channels the agent mounts itself. */
+export declare const BUILT_IN_CHANNELS: ReadonlySet<string>;
 /** A plugin that cannot be loaded. A `ConfigError`, so every command reports it as one. */
 export declare class PluginError extends ConfigError {
     constructor(message: string);
@@ -21,9 +25,10 @@ type CheckedTool = PluginTool | PluginReadTool;
  * promising an action nothing performs fails here, at startup (C6).
  * `agent plugin new` runs it on what it generates (specs/041).
  */
-export declare function checkPlugin(spec: string, value: unknown, taken: Map<string, string>): {
+export declare function checkPlugin(spec: string, value: unknown, taken: Map<string, string>, channelsTaken?: Map<string, string>): {
     name: string;
     tools: CheckedTool[];
+    channels: PluginChannel<unknown, unknown>[];
 };
 /** The packages `plugins.json` lists, or none when the file is absent. */
 export declare function listedPlugins(configDir: string): string[];

package/dist/plugins/loader.js

@@ -13,7 +13,7 @@ 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 { MAX_QUERY_LENGTH, MAX_RESULT_ITEMS, MAX_RESULT_TEXT_LENGTH, SUPPORTED_PLUGIN_API_VERSIONS, } from "./api.js";
+import { MAX_QUERY_LENGTH, SUPPORTED_CHANNEL_API_VERSIONS, MAX_RESULT_ITEMS, MAX_RESULT_TEXT_LENGTH, SUPPORTED_PLUGIN_API_VERSIONS, } 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';
@@ -25,7 +25,12 @@ export const BUILT_IN_TOOLS = new Set([
 ]);
 /** A tool name the loader accepts: lowercase snake case, at most 64 characters. */
 export const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
-const PLUGIN_KEYS = new Set(['name', 'apiVersion', 'tools']);
+/** A channel name the loader accepts: the path segment of its route (specs/038). */
+export const CHANNEL_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/** Channels the agent mounts itself. */
+export const BUILT_IN_CHANNELS = new Set(['manychat']);
+const PLUGIN_KEYS = new Set(['name', 'apiVersion', 'tools', 'channels']);
+const CHANNEL_KEYS = new Set(['name', 'apiVersion', 'inbound', 'parse', 'render', 'push']);
 const TOOL_KEYS = new Set(['name', 'description', 'parameters', 'perform', 'read', 'result']);
 const ENUM_KEYS = new Set(['type', 'values', 'description', 'optional']);
 const NUMBER_KEYS = new Set(['type', 'integer', 'min', 'max', 'description', 'optional']);
@@ -270,12 +275,49 @@ function checkTool(plugin, apiVersion, value, taken) {
     taken.set(name, plugin);
     return value;
 }
+/**
+ * Checks one channel (specs/038). Its `apiVersion` is its own, provisional,
+ * and apart from the plugin's tool API.
+ */
+function checkChannel(plugin, value, taken) {
+    if (!isObject(value))
+        throw new PluginError(`plugin ${plugin}: a channel is not an object`);
+    const name = value.name;
+    if (typeof name !== 'string' || !CHANNEL_NAME.test(name)) {
+        throw new PluginError(`plugin ${plugin}: channel name ${JSON.stringify(name)} must be lowercase letters, digits and dashes`);
+    }
+    const where = `plugin ${plugin}, channel ${name}`;
+    if (BUILT_IN_CHANNELS.has(name))
+        throw new PluginError(`${where}: takes a built-in channel's name`);
+    const owner = taken.get(name);
+    if (owner !== undefined)
+        throw new PluginError(`${where}: plugin ${owner} already defines it`);
+    const extra = unknownKeys(value, CHANNEL_KEYS);
+    if (extra.length > 0)
+        throw new PluginError(`${where}: unknown keys ${extra.join(', ')}`);
+    const apiVersion = value.apiVersion;
+    if (typeof apiVersion !== 'number' || !SUPPORTED_CHANNEL_API_VERSIONS.includes(apiVersion)) {
+        throw new PluginError(`${where}: apiVersion ${JSON.stringify(apiVersion)} is not supported; ` +
+            `this agent supports channel API ${SUPPORTED_CHANNEL_API_VERSIONS.join(' and ')} (specs/038)`);
+    }
+    // The schema the request is validated with before anything reads it (C3).
+    const inbound = value.inbound;
+    if (!isObject(inbound) || typeof inbound.safeParse !== 'function') {
+        throw new PluginError(`${where}: inbound must be a Zod schema`);
+    }
+    for (const key of ['parse', 'render', 'push']) {
+        if (typeof value[key] !== 'function')
+            throw new PluginError(`${where}: ${key} 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).
  * `agent plugin new` runs it on what it generates (specs/041).
  */
-export function checkPlugin(spec, value, taken) {
+export function checkPlugin(spec, value, taken, channelsTaken = new Map()) {
     if (!isObject(value)) {
         throw new PluginError(`plugin ${spec}: its default export is not a plugin (use definePlugin)`);
     }
@@ -288,19 +330,18 @@ export function checkPlugin(spec, value, taken) {
         throw new PluginError(`plugin ${name}: apiVersion ${JSON.stringify(apiVersion)} is not supported; ` +
             `this agent supports ${SUPPORTED_PLUGIN_API_VERSIONS.join(' and ')}`);
     }
-    // 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`);
     }
+    if (value.channels !== undefined && !Array.isArray(value.channels)) {
+        throw new PluginError(`plugin ${name}: channels must be an array`);
+    }
     const tools = (value.tools ?? []).map(tool => checkTool(name, apiVersion, tool, taken));
-    return { name, tools };
+    const channels = (value.channels ?? []).map(channel => checkChannel(name, channel, channelsTaken));
+    return { name, tools, channels };
 }
 /** The packages `plugins.json` lists, or none when the file is absent. */
 export function listedPlugins(configDir) {
@@ -338,8 +379,10 @@ export async function loadPlugins(configDir, options = {}) {
         return Plugins.NONE;
     const from = options.from ?? dirname(resolve(configDir));
     const taken = new Map();
+    const channelsTaken = new Map();
     const names = new Set();
     const loaded = [];
+    const channels = [];
     for (const spec of packages) {
         if (spec.startsWith('.') || spec.startsWith('/') || spec.includes('\\')) {
             throw new PluginError(`plugin ${spec}: list a package name, not a path`);
@@ -355,12 +398,13 @@ export async function loadPlugins(configDir, options = {}) {
         catch (error) {
             throw new PluginError(`plugin ${spec} failed to load: ${error.message}`);
         }
-        const plugin = checkPlugin(spec, module.default, taken);
+        const plugin = checkPlugin(spec, module.default, taken, channelsTaken);
         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 })));
+        channels.push(...plugin.channels.map(channel => ({ plugin: plugin.name, channel })));
     }
-    return new Plugins(loaded, [...names]);
+    return new Plugins(loaded, [...names], channels);
 }

package/dist/plugins/plugins.d.ts

@@ -1,7 +1,7 @@
 import { type ToolSet } from 'ai';
 import type { ActionPerformer } from '../channels/manychat/client.ts';
 import type { ActionStage } from '../agent/tools.ts';
-import type { PluginLogger, PluginReadTool, PluginTool } from './api.ts';
+import type { PluginChannel, PluginLogger, PluginReadTool, PluginTool } from './api.ts';
 import { type PluginReads } from './reads.ts';
 /**
  * How long the agent waits for a plugin's `perform`. Past it the signal
@@ -24,6 +24,11 @@ export interface LoadedTool {
     /** A write tool, which declares `perform`, or a read tool, which declares `read` (specs/039). */
     tool: PluginTool | PluginReadTool;
 }
+export interface LoadedChannel {
+    /** The plugin that declared it. */
+    plugin: string;
+    channel: PluginChannel;
+}
 /**
  * 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).
@@ -40,18 +45,21 @@ export declare class Plugins {
     private readonly readsByName;
     /** The loaded plugins' names, in the order `plugins.json` lists them. */
     readonly names: readonly string[];
-    constructor(tools: readonly LoadedTool[], names?: readonly string[]);
+    /** The channels the plugins add, each mounted beside ManyChat's (specs/038). */
+    readonly channels: readonly LoadedChannel[];
+    constructor(tools: readonly LoadedTool[], names?: readonly string[], channels?: readonly LoadedChannel[]);
     /** Whether any plugin adds a tool, of either kind. */
     get hasTools(): boolean;
     /** Whether any plugin adds a write tool: the prompt's staged-tool lines follow this (specs/039). */
     get hasWriteTools(): boolean;
     /** Whether any plugin adds a read tool: the prompt's read lines follow this (specs/039). */
     get hasReadTools(): boolean;
-    /** Each loaded plugin's tools by kind, as `agent config check` reports them. */
+    /** Each loaded plugin's tools by kind and its channels, as `agent config check` reports them. */
     summary(): {
         plugin: string;
         writes: string[];
         reads: string[];
+        channels: string[];
     }[];
     /**
      * Adds each read tool to the turn's tools (specs/039). A call is performed

package/dist/plugins/plugins.js

@@ -69,7 +69,9 @@ export class Plugins {
     readsByName;
     /** The loaded plugins' names, in the order `plugins.json` lists them. */
     names;
-    constructor(tools, names = []) {
+    /** The channels the plugins add, each mounted beside ManyChat's (specs/038). */
+    channels;
+    constructor(tools, names = [], channels = []) {
         const writes = new Map();
         const reads = new Map();
         for (const { plugin, tool } of tools) {
@@ -81,6 +83,7 @@ export class Plugins {
         this.byName = writes;
         this.readsByName = reads;
         this.names = names;
+        this.channels = channels;
     }
     /** Whether any plugin adds a tool, of either kind. */
     get hasTools() {
@@ -94,9 +97,12 @@ export class Plugins {
     get hasReadTools() {
         return this.readsByName.size > 0;
     }
-    /** Each loaded plugin's tools by kind, as `agent config check` reports them. */
+    /** Each loaded plugin's tools by kind and its channels, as `agent config check` reports them. */
     summary() {
         return this.names.map(plugin => ({
+            channels: this.channels
+                .filter(entry => entry.plugin === plugin)
+                .map(entry => entry.channel.name),
             plugin,
             writes: [...this.byName.values()]
                 .filter(entry => entry.plugin === plugin)

package/dist/routes/turn.d.ts

@@ -38,6 +38,13 @@ export interface TurnDeps {
      * request; without it, turns run side by side.
      */
     lanes?: TurnLanes | undefined;
+    /**
+     * The plugin channel the turn arrived on (specs/038); ManyChat when absent.
+     * Its contacts are bound by the channel's own auth and carry no token, its
+     * turns are offered no `tools.json` tool, and its queued replies go out
+     * through its adapter.
+     */
+    channel?: string | undefined;
 }
 export interface TurnResult {
     reply: AgentReply;
@@ -72,6 +79,13 @@ export declare class TurnHandler {
     private readonly tokens;
     private readonly nudges;
     constructor(deps: TurnDeps);
+    /** Queues a reply for the turn's channel: ManyChat, or a plugin's (specs/038). */
+    private enqueue;
+    /**
+     * A plugin channel's contact is bound by the channel's own auth: it has no
+     * token to present, and none is issued (specs/038).
+     */
+    private bindingOf;
     /**
      * Runs the turn once the contact's previous one has settled (specs/037 §
      * Turns that enter history run one at a time). A turn still waiting at its

package/dist/routes/turn.js

@@ -89,6 +89,17 @@ export class TurnHandler {
         this.tokens = new ContactTokens(deps.db, deps.tokenWriter);
         this.nudges = new NudgeStore(deps.db);
     }
+    /** Queues a reply for the turn's channel: ManyChat, or a plugin's (specs/038). */
+    enqueue(input) {
+        return this.queue.enqueue({ ...input, channel: this.deps.channel });
+    }
+    /**
+     * A plugin channel's contact is bound by the channel's own auth: it has no
+     * token to present, and none is issued (specs/038).
+     */
+    bindingOf(known, inbound) {
+        return this.deps.channel !== undefined ? 'bound' : bindingFor(known, inbound.contactToken);
+    }
     /**
      * Runs the turn once the contact's previous one has settled (specs/037 §
      * Turns that enter history run one at a time). A turn still waiting at its
@@ -113,7 +124,7 @@ export class TurnHandler {
             slot.leave();
             throw error;
         });
-        const binding = bindingFor(known, inbound.contactToken);
+        const binding = this.bindingOf(known, inbound);
         if (binding === 'unbound' && tokensEnforced) {
             slot.leave();
             return this.run(inbound, { deadlineAt });
@@ -186,7 +197,7 @@ export class TurnHandler {
         let conversation;
         try {
             conversation = await this.store.find(inbound.tenantId, inbound.subscriberId);
-            await this.queue.enqueue({
+            await this.enqueue({
                 tenantId: inbound.tenantId,
                 subscriberId: inbound.subscriberId,
                 conversationId: conversation?.id ?? null,
@@ -214,7 +225,7 @@ export class TurnHandler {
         // (specs/019). Without it the request is answered from its own message
         // alone, and neither reads nor extends the contact's history.
         const known = await this.store.find(inbound.tenantId, inbound.subscriberId);
-        const binding = bindingFor(known, inbound.contactToken);
+        const binding = this.bindingOf(known, inbound);
         // During the rollout a request without the token is treated as it was
         // before specs/019, so nobody loses context before their token lands.
         const bound = binding !== 'unbound' || !tokensEnforced;
@@ -249,7 +260,7 @@ export class TurnHandler {
             if (!(await mustQueue()))
                 return result;
             try {
-                await this.queue.enqueue({
+                await this.enqueue({
                     tenantId: inbound.tenantId,
                     subscriberId: inbound.subscriberId,
                     conversationId: conversation.id,
@@ -502,6 +513,7 @@ export class TurnHandler {
                 pluginReads,
                 flows,
                 beforeFlow: sendOpening,
+                builtInTools: this.deps.channel === undefined,
             })
                 .then(result => ({ kind: 'model', result }));
         // Inside the race, as a flow the model calls is (specs/029): a send that
@@ -581,7 +593,7 @@ export class TurnHandler {
                 return result;
             }
             try {
-                await this.queue.enqueue({
+                await this.enqueue({
                     tenantId: inbound.tenantId,
                     subscriberId: inbound.subscriberId,
                     conversationId: conversation.id,
@@ -652,7 +664,7 @@ export class TurnHandler {
                         // A silent response gave the contact nothing yet, so the holding
                         // line it held back goes out now, after the flow (specs/030).
                         if (silent) {
-                            await this.queue.enqueue({
+                            await this.enqueue({
                                 tenantId: inbound.tenantId,
                                 subscriberId: inbound.subscriberId,
                                 conversationId: conversation.id,
@@ -683,7 +695,7 @@ export class TurnHandler {
                             logger.info({ interventions: done.result.interventions, deferred: true }, 'guardrails intervened');
                         }
                     }
-                    await this.queue.enqueue({
+                    await this.enqueue({
                         tenantId: inbound.tenantId,
                         subscriberId: inbound.subscriberId,
                         conversationId: conversation.id,
@@ -854,6 +866,7 @@ export class TurnHandler {
             pluginReads: ctx.pluginReads,
             flows: ctx.flows,
             beforeFlow: ctx.beforeFlow,
+            builtInTools: this.deps.channel === undefined,
             media: {
                 // `unsupported` never resolves; it always takes the fallback above.
                 kind: media.kind,

package/dist/server.js

@@ -5,12 +5,13 @@ import underPressure from '@fastify/under-pressure';
 import swagger from '@fastify/swagger';
 import { serializerCompiler, validatorCompiler, jsonSchemaTransform, } from 'fastify-type-provider-zod';
 import { ManyChatInbound, ManyChatResponse } from "./contracts/manychat.js";
-import { capabilitiesFor } from "./contracts/config.js";
+import { capabilitiesFor, NO_TOOLS } from "./contracts/config.js";
 import { acceptsImages, resolveModel, resolveTranscriptionModel } from "./agent/registry.js";
 import { GenerateTextRunner } from "./agent/runner.js";
 import { SdkTranscriber } from "./agent/transcriber.js";
 import { ManyChatAdapter } from "./channels/manychat/adapter.js";
 import { manychatClientFor } from "./channels/manychat/client.js";
+import { channelAdapters } from "./channels/plugin/adapter.js";
 import { ManyChatMediaFetcher } from "./channels/manychat/media.js";
 import { detectFfmpeg, FfmpegVideoSplitter } from "./media/ffmpeg.js";
 import { MediaResolver } from "./media/resolver.js";
@@ -22,6 +23,21 @@ 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';
+/**
+ * A plugin channel's turns issue no token, so nothing is ever written
+ * (specs/038). Refusing, should that change unnoticed.
+ */
+const NO_TOKEN_WRITER = {
+    writeToken: () => Promise.reject(new Error('a plugin channel writes no contact token')),
+};
+/**
+ * What a plugin channel's turn performs a built-in action through. None is
+ * offered there, so none is staged; one that were would fail, never reach
+ * ManyChat for a contact who is not on it (specs/038, C6).
+ */
+const MANYCHAT_UNAVAILABLE = {
+    performAction: () => Promise.reject(new Error('a plugin channel performs no ManyChat action')),
+};
 /**
  * The whole production composition. Plugins are registered before any route is
  * declared, inside this function, because `@fastify/rate-limit` and anything
@@ -127,6 +143,16 @@ export async function buildServer(opts) {
         // And their offering, read per request so a reload reaches it (specs/028).
         offeringField: tenant().tools?.fields.find(field => field.offering)?.field,
     });
+    // The plugins' channels, each mounted beside ManyChat's route (specs/038).
+    const channels = channelAdapters(plugins, app.log);
+    /** How each message route renders a handoff, by route. */
+    const handoffs = new Map([
+        [
+            MESSAGE_ROUTE,
+            (handoff, secret) => adapter.render(handoff, { capabilities, ...callbackFor(secret) }),
+        ],
+        ...[...channels.values()].map(channel => [channel.route, (handoff) => channel.render(handoff)]),
+    ]);
     app.setErrorHandler((error, request, reply) => {
         // Client errors (rate limit, oversized body, validation) keep Fastify's
         // answer. Validation runs after authentication, so its detail reaches only
@@ -144,13 +170,16 @@ export async function buildServer(opts) {
             // parameters, and those include the contact's text (C5).
             request.log.error({ error: { name: error.name, code: error.code, message: redactText(error.message) } }, 'unhandled error');
         }
-        // On the message route a failure, overload included, is a handoff to a
+        // On a message route a failure, overload included, is a handoff to a
         // person, never a 500 carrying the error or a 503 the contact never sees
         // (C6, specs/017 § An error on the message route is a handoff, not a 500).
-        if (request.routeOptions.url === MESSAGE_ROUTE &&
-            isAuthenticated(request, env.MANYCHAT_SHARED_SECRET)) {
+        // A plugin channel's route hands off the same way, through its own
+        // renderer (specs/038).
+        const route = request.routeOptions.url;
+        const render = route === undefined ? undefined : handoffs.get(route);
+        if (render && isAuthenticated(request, env.MANYCHAT_SHARED_SECRET)) {
             try {
-                const handoff = adapter.render(escalationReply('low_confidence', tenant().rules.messages.escalation), { capabilities, ...callbackFor(bearerToken(request.headers.authorization)) });
+                const handoff = render(escalationReply('low_confidence', tenant().rules.messages.escalation), bearerToken(request.headers.authorization));
                 // under-pressure sets it for its 503; on a 200 it means nothing.
                 reply.removeHeader('retry-after');
                 return reply.code(200).send(handoff);
@@ -180,46 +209,29 @@ export async function buildServer(opts) {
     // One for the process, so every request for a contact shares the order
     // (specs/037). Past this bound everything a turn runs has ended (C6).
     const lanes = new TurnLanes(env.MODEL_ABORT_MS + env.RACE_DEADLINE_MS);
-    app.post(MESSAGE_ROUTE, {
-        onRequest: createSharedSecretGuard(env.MANYCHAT_SHARED_SECRET),
-        // After the Dynamic Block response is sent, never before: the text the
-        // actions follow has to leave first (specs/012 § Actions follow the text).
-        onResponse: async (request) => {
-            const perform = afterResponse.get(request);
-            afterResponse.delete(request);
-            if (perform)
-                await perform();
-        },
-        schema: {
-            summary: 'ManyChat Dynamic Block webhook',
-            body: ManyChatInbound,
-            response: { 200: ManyChatResponse },
-            security: [{ sharedSecret: [] }],
-        },
-    }, async (request) => {
-        const inbound = adapter.parse(request.body, {
-            tenantId: env.TENANT_ID,
-            channel: env.CHANNEL,
-            logger: request.log,
-        });
+    // After the response is sent, never before: the text the actions follow
+    // has to leave first (specs/012 § Actions follow the text).
+    const performAfterResponse = async (request) => {
+        const perform = afterResponse.get(request);
+        afterResponse.delete(request);
+        if (perform)
+            await perform();
+    };
+    /** One turn, on any message route; what differs between channels is `deps`. */
+    const runTurn = async (request, inbound, deps) => {
         // Constructed per request: `tenant()` re-reads config, which SIGHUP can
         // have reloaded since the last turn.
         const handler = new TurnHandler({
             db,
             runner,
             rules: tenant().rules,
-            tools: tenant().tools,
             raceDeadlineMs: env.RACE_DEADLINE_MS,
             modelAbortMs: env.MODEL_ABORT_MS,
             logger: request.log,
-            tokenWriter: manychatClient,
-            tokensEnforced: env.CONTACT_TOKENS_ENFORCED,
-            // A plugin action goes to its plugin, the rest to ManyChat (specs/036).
-            actions: plugins.performer(manychatClient, request.log),
-            contacts,
             plugins,
             media,
             lanes,
+            ...deps,
         });
         const turn = await handler.handle(inbound);
         const { reply, outcome, conversationId, binding } = turn;
@@ -233,14 +245,77 @@ export async function buildServer(opts) {
             outcome,
             binding,
             escalated: reply.escalate,
+            ...(deps.channel ? { channel: deps.channel } : {}),
             ...(turn.silent ? { silent: true } : {}),
         }, 'turn complete');
-        return adapter.render(reply, {
+        return turn;
+    };
+    app.post(MESSAGE_ROUTE, {
+        onRequest: createSharedSecretGuard(env.MANYCHAT_SHARED_SECRET),
+        onResponse: performAfterResponse,
+        schema: {
+            summary: 'ManyChat Dynamic Block webhook',
+            body: ManyChatInbound,
+            response: { 200: ManyChatResponse },
+            security: [{ sharedSecret: [] }],
+        },
+    }, async (request) => {
+        const inbound = adapter.parse(request.body, {
+            tenantId: env.TENANT_ID,
+            channel: env.CHANNEL,
+            logger: request.log,
+        });
+        const turn = await runTurn(request, inbound, {
+            tokenWriter: manychatClient,
+            tokensEnforced: env.CONTACT_TOKENS_ENFORCED,
+            // A plugin action goes to its plugin, the rest to ManyChat (specs/036).
+            actions: plugins.performer(manychatClient, request.log),
+            contacts,
+            tools: tenant().tools,
+        });
+        return adapter.render(turn.reply, {
             capabilities,
             silent: turn.silent,
             // Re-registered every turn so the loop stays server-side (specs/002).
             ...callbackFor(bearerToken(request.headers.authorization)),
         });
     });
+    // Each plugin channel runs exactly as ManyChat's route does: the same auth,
+    // rate limit, budget, race, order and outbox. What it is not given is
+    // ManyChat: no contact token, no `tools.json` tool, no contact read
+    // (specs/038).
+    for (const channel of channels.values()) {
+        app.post(channel.route, {
+            onRequest: createSharedSecretGuard(env.MANYCHAT_SHARED_SECRET),
+            // Its own schema, before anything reads the body (C3). Its detail is
+            // not returned: the plugin's schema is the plugin's.
+            preValidation: async (request, reply) => {
+                if (!channel.accepts(request.body)) {
+                    await reply.code(400).send({ error: 'invalid request' });
+                }
+            },
+            onResponse: performAfterResponse,
+            schema: {
+                summary: `Plugin channel ${channel.name} (provisional, specs/038)`,
+                security: [{ sharedSecret: [] }],
+            },
+        }, async (request) => {
+            const inbound = channel.parse(request.body, {
+                tenantId: env.TENANT_ID,
+                channel: channel.name,
+            });
+            const turn = await runTurn(request, inbound, {
+                tokenWriter: NO_TOKEN_WRITER,
+                tokensEnforced: false,
+                actions: plugins.performer(MANYCHAT_UNAVAILABLE, request.log),
+                contacts: undefined,
+                tools: NO_TOOLS,
+                channel: channel.name,
+            });
+            // A silent response carries no message: the reply follows from the
+            // outbox (specs/030, specs/037).
+            return channel.render(turn.silent ? { ...turn.reply, messages: [] } : turn.reply);
+        });
+    }
     return { app, runner };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "manychat-ai-agent",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "A provider-agnostic conversational AI agent gateway that bridges no-code chat platforms to any LLM.",
   "license": "MIT",
   "repository": {