manychat-ai-agent 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.25.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.24.1...v0.25.0) (2026-10-16)
+
+
+### Features
+
+* a silent payment-link flow leaves the link to the reply ([b4d019e](https://github.com/pedronastasi/manychat-ai-agent/commit/b4d019e275fc0073acc82f1361eec0e59a68c163))
+* a silent payment-link flow leaves the link to the reply ([11d3929](https://github.com/pedronastasi/manychat-ai-agent/commit/11d3929ae3c4e734d42fab62022dab33ac214e3b))
+
+
+### Bug Fixes
+
+* an offering's link does not count as one it is a prefix of ([426ade9](https://github.com/pedronastasi/manychat-ai-agent/commit/426ade9850e3e72354697c9961218558ad8b6d05))
+
+
+### Specs and Docs
+
+* **specs:** a silent payment flow leaves the link to the reply ([4611b15](https://github.com/pedronastasi/manychat-ai-agent/commit/4611b15744f4a81bd3cf6943a2a1f39644d2bb7f))
+
 ## [0.24.1](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.24.0...v0.24.1) (2026-10-16)
 
 

package/dist/agent/guardrails.d.ts

@@ -54,8 +54,14 @@ export declare function escalationReply(reason: EscalationReason, message: strin
  *
  * `earlierReplies` is the text of the agent's earlier turns in the
  * conversation, which the repetition check compares against (specs/013).
+ *
+ * `paymentLink` is the link the reply must carry because the turn sent a
+ * silent payment-link flow (specs/023 § A silent payment flow leaves the link
+ * to the reply).
  */
-export declare function applyGuardrails(raw: unknown, rules: Rules, earlierReplies?: readonly string[]): GuardedReply;
+export declare function applyGuardrails(raw: unknown, rules: Rules, earlierReplies?: readonly string[], options?: {
+    paymentLink?: string | undefined;
+}): GuardedReply;
 /**
  * Flags prices that do not appear in the catalog.
  *

package/dist/agent/guardrails.js

@@ -110,8 +110,12 @@ export function escalationReply(reason, message) {
  *
  * `earlierReplies` is the text of the agent's earlier turns in the
  * conversation, which the repetition check compares against (specs/013).
+ *
+ * `paymentLink` is the link the reply must carry because the turn sent a
+ * silent payment-link flow (specs/023 § A silent payment flow leaves the link
+ * to the reply).
  */
-export function applyGuardrails(raw, rules, earlierReplies = []) {
+export function applyGuardrails(raw, rules, earlierReplies = [], options = {}) {
     const interventions = [];
     const parsed = AgentReply.safeParse(raw);
     if (!parsed.success) {
@@ -200,12 +204,14 @@ export function applyGuardrails(raw, rules, earlierReplies = []) {
     // matters is that exactly one question ends the turn, not which.
     const bodyMessages = reply.messages;
     const body = bodyMessages.at(-1);
+    let questionAppended = false;
     if (reply.closing_question !== null && !reply.escalate) {
         if (body !== undefined && endsWithQuestion(body)) {
             interventions.push('closing_question_already_in_body');
         }
         else {
             reply = { ...reply, messages: [...reply.messages, reply.closing_question] };
+            questionAppended = true;
         }
     }
     // Verbatim repetition, most often an earlier answer replayed in reply to a
@@ -231,10 +237,59 @@ export function applyGuardrails(raw, rules, earlierReplies = []) {
             // is nothing to ask and nothing to hand off.
             interventions.push('duplicate_replaced');
             reply = { ...reply, messages: [closer], closing_question: null };
+            questionAppended = false;
         }
     }
+    // A silent payment-link flow sent nothing, so a reply without the link
+    // leaves the contact recorded at link_sent with no way to pay (specs/023
+    // § A silent payment flow leaves the link to the reply). Checked last, on
+    // what would be delivered. The link goes on its own line at the end of the
+    // body, so the turn still ends on its one question. Skipped on an
+    // escalation: the person taking over sends it.
+    const link = options.paymentLink;
+    if (link !== undefined && !reply.escalate && !carriesLink(reply.messages, link)) {
+        interventions.push('payment_link_added');
+        reply = { ...reply, messages: withLink(reply.messages, link, questionAppended) };
+    }
     return { reply, interventions, ...(escalatedBy ? { escalatedBy } : {}) };
 }
+/**
+ * The messages with the link on its own line after the body's last one, or as
+ * a message of its own ahead of a question the body ends on or that would not
+ * fit beside it.
+ */
+function withLink(messages, link, questionAppended) {
+    const last = messages.length - 1;
+    const asked = questionAppended || endsWithQuestion(messages[last] ?? '');
+    const at = asked ? last - 1 : last;
+    const target = messages[at];
+    if (target === undefined || target.length + link.length + 1 > MAX_MESSAGE_CHARS) {
+        return messages.toSpliced(at + 1, 0, link);
+    }
+    return messages.with(at, `${target}\n${link}`);
+}
+/**
+ * Whether any message carries the link, as the catalog writes it or with its
+ * percent-encoding undone, which is how a model often copies a URL with an
+ * accented path. A trailing slash is optional.
+ *
+ * The link must end where the URL in the message ends: another offering's
+ * link that starts with this one (`…/foundation-plus` for `…/foundation`) is
+ * not this link, and counting it would leave the contact with the wrong one.
+ */
+function carriesLink(messages, link) {
+    const bare = (url) => url.replace(/\/+$/, '');
+    let decoded = link;
+    try {
+        decoded = decodeURI(link);
+    }
+    catch {
+        // A malformed escape: only the link as written can match.
+    }
+    const patterns = [...new Set([bare(link), bare(decoded)])].map(form => new RegExp(`${escapeRegExp(form)}/?(?![\\p{L}\\p{N}_%/-])`, 'u'));
+    return messages.some(message => patterns.some(pattern => pattern.test(message)));
+}
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 /** Numbers with a currency cue nearby, e.g. "$45.000", "45000 pesos". */
 const PRICE_PATTERN = /(?:\$\s?)([\d][\d.,]{2,})|([\d][\d.,]{2,})\s?(?:pesos|ars|usd)/gi;
 /** Digits only, so "45.000", "45,000" and "45000" compare equal. */

package/dist/agent/prompt.d.ts

@@ -99,6 +99,12 @@ opening?: {
 reads?: readonly {
     tool: string;
     result: ReadResult;
+}[], 
+/** The tenant's flows, for which of them send the contact nothing (specs/023). */
+flows?: readonly {
+    id: string;
+    role?: string | undefined;
+    silent?: boolean | undefined;
 }[]): string;
 /**
  * The server's note on an earlier turn of what it performed, or null when it

package/dist/agent/prompt.js

@@ -409,7 +409,16 @@ function salesSection(tools) {
                     'moves forward: a write to an earlier stage is refused.',
                     ...(link
                         ? [
-                            `The payment link is the flow ${link.id}. It is refused before prepared, unless the contact`,
+                            ...(link.silent
+                                ? [
+                                    `The payment link is recorded by the flow ${link.id}, which is silent: it sends the`,
+                                    'contact nothing. Every time you send it, write the link of the contact’s offering from',
+                                    'the CATALOG in the same reply: the flow does not deliver it. It is refused before',
+                                    'prepared, unless the contact',
+                                ]
+                                : [
+                                    `The payment link is the flow ${link.id}. It is refused before prepared, unless the contact`,
+                                ]),
                             'asks for it: a contact whose message asks for the link, the payment methods or how to pay',
                             'gets it, qualified or not, and you pass contactAsked true. Never pass it otherwise.',
                         ]
@@ -528,15 +537,35 @@ contact,
 /** The opening the turn's prospect write queued, if it did (specs/034). */
 opening, 
 /** Each plugin read tool's last successful read, its text still fenced (specs/039). */
-reads = []) {
+reads = [], 
+/** The tenant's flows, for which of them send the contact nothing (specs/023). */
+flows = []) {
     // Flows only: a stage write sent ahead of a payment link is not news to the contact.
     const sent = (stage.sent ?? []).filter(entry => entry.action.tool === 'send_flow');
-    const went = sent.filter(entry => entry.records[0]?.status === 'performed');
+    const flowOf = (entry) => flows.find(flow => flow.id === entry.action.id);
+    const performed = sent.filter(entry => entry.records[0]?.status === 'performed');
+    const went = performed.filter(entry => !flowOf(entry)?.silent);
+    // A silent flow is not something the contact received, and a reply that
+    // treats it as one leaves out what it stands for (specs/023 § A silent
+    // payment flow leaves the link to the reply).
+    const recorded = performed.filter(entry => flowOf(entry)?.silent);
+    const silentLink = (action) => {
+        const flow = flows.find(entry => entry.id === action.id);
+        return action.tool === 'send_flow' && flow?.silent === true && flow.role === 'payment_link';
+    };
+    const link = recorded.some(entry => silentLink(entry.action));
+    const stagedLink = stage.staged.some(silentLink);
     const failed = sent.filter(entry => entry.records[0]?.status !== 'performed');
     const lines = [
         went.length > 0
             ? `SENT: Already sent to the contact, who receives it before your reply: ${went.map(entry => describeAction(entry.action)).join(', ')}. Your reply follows it; do not repeat what it contains.`
             : null,
+        recorded.length > 0
+            ? `RECORDED: ${recorded.map(entry => describeAction(entry.action)).join(', ')}. Silent: the contact received nothing from it. Write your reply in full, as if it had not been sent.` +
+                (link
+                    ? ' The payment link is yours to write: put the link of the contact’s offering from the CATALOG in this reply.'
+                    : '')
+            : null,
         failed.length > 0
             ? `NOT SENT: ManyChat refused: ${failed.map(entry => describeAction(entry.action)).join(', ')}. Do not say it was sent.`
             : null,
@@ -545,6 +574,9 @@ reads = []) {
             : sent.length > 0
                 ? null
                 : 'ACTIONS: None of your tool calls were staged.',
+        stagedLink
+            ? 'The payment link flow is silent and sends the contact nothing: put the link of the contact’s offering from the CATALOG in this reply.'
+            : null,
         stage.dropped.length > 0
             ? `Not staged, over the limit of ${MAX_ACTIONS_PER_TURN} per turn: ${stage.dropped.map(describeAction).join(', ')}.`
             : null,

package/dist/agent/runner.js

@@ -4,7 +4,7 @@ import { NO_TOOLS, offersTools } from "../contracts/config.js";
 import { actionsNote, buildSystemPrompt, offeringNotice, fenceUserText, funnelNotice, mediaNotice, intentNotice, nudgeNotice, stagedNotice, } from "./prompt.js";
 import { applyGuardrails, escalationReply } from "./guardrails.js";
 import { estimateCostUsd, supportsTemperature } from "./registry.js";
-import { ActionStage, buildTools, offeringField, funnelField, intentField, MAX_STEPS, openingFlow, stagesProspect, } from "./tools.js";
+import { ActionStage, buildTools, offeringField, funnelField, intentField, MAX_STEPS, openingFlow, silentPaymentLink, stagesProspect, } from "./tools.js";
 import { renderPlaybook } from "../learning/playbook.js";
 /**
  * An earlier turn as the model reads it. An agent turn is followed by the
@@ -171,7 +171,7 @@ export class GenerateTextRunner {
                             ...messages,
                             {
                                 role: 'user',
-                                content: stagedNotice(stage, reads?.latest, opening && stagesProspect(stage, tenantTools) ? opening : undefined, pluginReads?.latest),
+                                content: stagedNotice(stage, reads?.latest, opening && stagesProspect(stage, tenantTools) ? opening : undefined, pluginReads?.latest, tenantTools.flows),
                             },
                         ],
                     }
@@ -242,7 +242,21 @@ export class GenerateTextRunner {
             };
         }
         const earlierReplies = history.filter(turn => turn.role === 'agent').map(turn => turn.text);
-        const guarded = applyGuardrails(output, config.rules, earlierReplies);
+        const paymentLink = silentPaymentLink(tenantTools, config.catalog, stage, contact);
+        let guarded = applyGuardrails(output, config.rules, earlierReplies, {
+            paymentLink: paymentLink ?? undefined,
+        });
+        // Sent, with no link to put in the reply: the loader's checks leave only a
+        // contact with no offering recorded. A reply without the link would leave
+        // them at link_sent with no way to pay, so a person finishes the turn
+        // (specs/023 § A silent payment flow leaves the link to the reply, C6).
+        if (paymentLink === null && !guarded.reply.escalate) {
+            guarded = {
+                reply: escalationReply('low_confidence', config.rules.messages.escalation),
+                interventions: [...guarded.interventions, 'payment_link_unknown'],
+                escalatedBy: 'error',
+            };
+        }
         return {
             reply: guarded.reply,
             interventions: guarded.interventions,

package/dist/agent/tools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolSet } from 'ai';
-import type { Tools, INTENT_VALUES } from '../contracts/config.ts';
+import type { Catalog, 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';
@@ -122,7 +122,22 @@ export declare function paymentLinkFlow(config: Tools): {
     onStage?: "qualifying" | "nurturing" | "offered" | "prepared" | undefined;
     offering?: string | undefined;
     settleSeconds?: number | undefined;
+    silent?: boolean | undefined;
 } | undefined;
+/**
+ * The link a reply must carry because the turn sent a silent payment-link
+ * flow, which leaves the link to the reply (specs/023 § A silent payment flow
+ * leaves the link to the reply). `undefined` when the turn neither sent such
+ * a flow nor staged it to be sent after the reply.
+ *
+ * The link is the catalog `url` of the turn's offering: one written this turn,
+ * else the contact's, else the catalog's only offering. `null` when the flow
+ * went out and no offering or link is known, which the loader's checks leave
+ * to a contact with no offering recorded yet.
+ */
+export declare function silentPaymentLink(config: Tools, catalog: Catalog, stage: ActionStage, contact: {
+    offering?: string | undefined;
+} | undefined): string | null | undefined;
 /** The flow the server sends on a contact's prospect turn, if the tenant marked one (specs/034). */
 export declare function openingFlow(config: Tools): {
     id: string;
@@ -133,6 +148,7 @@ export declare function openingFlow(config: Tools): {
     onStage?: "qualifying" | "nurturing" | "offered" | "prepared" | undefined;
     offering?: string | undefined;
     settleSeconds?: number | undefined;
+    silent?: boolean | undefined;
 } | undefined;
 /** The field the contact's offering is kept in, if the tenant marked one (specs/028). */
 export declare function offeringField(config: Tools): {

package/dist/agent/tools.js

@@ -192,6 +192,33 @@ export function funnelField(config) {
 export function paymentLinkFlow(config) {
     return config.flows.find(flow => flow.role === 'payment_link');
 }
+/**
+ * The link a reply must carry because the turn sent a silent payment-link
+ * flow, which leaves the link to the reply (specs/023 § A silent payment flow
+ * leaves the link to the reply). `undefined` when the turn neither sent such
+ * a flow nor staged it to be sent after the reply.
+ *
+ * The link is the catalog `url` of the turn's offering: one written this turn,
+ * else the contact's, else the catalog's only offering. `null` when the flow
+ * went out and no offering or link is known, which the loader's checks leave
+ * to a contact with no offering recorded yet.
+ */
+export function silentPaymentLink(config, catalog, stage, contact) {
+    const link = paymentLinkFlow(config);
+    if (!link?.silent)
+        return undefined;
+    const sent = stage.sent.some(entry => entry.action.tool === 'send_flow' &&
+        entry.action.id === link.id &&
+        entry.records[0]?.status === 'performed');
+    const staged = stage.staged.some(action => action.tool === 'send_flow' && action.id === link.id);
+    if (!sent && !staged)
+        return undefined;
+    const written = stage.staged.findLast((action) => action.tool === 'set_field' && action.offering === true);
+    const id = written?.value ??
+        contact?.offering ??
+        (catalog.offerings.length === 1 ? catalog.offerings[0].id : undefined);
+    return catalog.offerings.find(offering => offering.id === id)?.url ?? null;
+}
 /** The flow the server sends on a contact's prospect turn, if the tenant marked one (specs/034). */
 export function openingFlow(config) {
     return config.flows.find(flow => flow.role === 'opening');
@@ -299,12 +326,18 @@ const catalogOf = (entries) => entries
     const notes = [
         entry.offering === undefined ? null : `offering ${entry.offering}`,
         entry.onStage === undefined ? null : `sent by the system when you record ${entry.onStage}`,
+        entry.silent ? 'silent: sends the contact nothing' : null,
     ].filter(Boolean);
     return `- ${entry.id}${notes.length > 0 ? ` (${notes.join('; ')})` : ''}: ${entry.description}`;
 })
     .join('\n');
 const STAGED = 'The action is staged, not performed: it happens after your reply is sent, and not at all if the turn escalates.';
 const SENT_NOW = 'The flow is sent when you call this, before your reply: the contact receives it first and your reply follows it. Do not repeat what it contains. The result says whether it went out.';
+const SILENT = 'A silent flow sends the contact nothing: write your reply in full, as if it had not been sent.';
+/** The note a silent flow's result carries; the payment link's names the link. */
+const silentResult = (role) => role === 'payment_link'
+    ? 'The contact received nothing from this flow. Your reply must carry the link of the contact’s offering from the CATALOG.'
+    : 'The contact received nothing from this flow. Write your reply in full, as if it had not been sent.';
 const CONTACT_ASKED = 'The payment link is refused before the stage is prepared. Pass contactAsked: true only when the contact’s message this turn asks for the link, the payment methods or how to pay; it is recorded.';
 const STAGED_NOTE = 'The note is staged, not written: it is written after your reply is sent. It replaces what the note held, so read it first with get_contact to add to it.';
 /**
@@ -419,6 +452,7 @@ options = {}) {
         const gated = funnel !== undefined && unsent.some(flow => flow.role === 'payment_link');
         tools.send_flow = tool({
             description: `Send the contact one of these flows.\n${listing}\n${sends ? SENT_NOW : STAGED}` +
+                (unsent.some(flow => flow.silent) ? `\n${SILENT}` : '') +
                 (gated ? `\n${CONTACT_ASKED}` : ''),
             inputSchema: gated
                 ? z.object({ flow: z.enum(idsOf(unsent)), contactAsked: z.boolean().optional() })
@@ -466,8 +500,14 @@ options = {}) {
                     ...(followOn ? { followOn } : {}),
                     ...(asked ? { contactAsked: true } : {}),
                 };
-                if (!sends)
-                    return { staged: stage.stage(action) };
+                // What a silent flow leaves to the reply, said where the model reads
+                // the outcome (specs/023 § A silent payment flow leaves the link to
+                // the reply).
+                const silent = entry.silent ? { silent: silentResult(entry.role) } : {};
+                if (!sends) {
+                    const staged = stage.stage(action);
+                    return staged ? { staged, ...silent } : { staged };
+                }
                 // The opening goes first on the prospect turn (specs/034). A payment
                 // link is counted at link_sent before the await, so a funnel or offering
                 // write made beside it is refused rather than landing after it (specs/029).
@@ -490,7 +530,9 @@ options = {}) {
                     ? stage.staged.filter(staged => staged.tool === 'set_field' && staged.id === funnel.id)
                     : [];
                 const sent = await stage.send(action, sends, first);
-                return sent === undefined ? { sent: false, reason: 'over the per-turn limit' } : { sent };
+                if (sent === undefined)
+                    return { sent: false, reason: 'over the per-turn limit' };
+                return sent ? { sent, ...silent } : { sent };
             },
         });
     }

package/dist/config/loader.js

@@ -84,6 +84,22 @@ function offeringMismatches(tools, catalog) {
             : tools.flows
                 .filter(flow => flow.offering !== undefined)
                 .map(flow => `flow '${flow.id}' has an offering, but no field is marked "offering"`)),
+        // A silent payment flow leaves the link to the reply, and the server puts
+        // the contact's offering's link there when the reply leaves it out, so
+        // that link must exist and the offering must be knowable (specs/023
+        // § A silent payment flow leaves the link to the reply).
+        ...tools.flows
+            .filter(flow => flow.role === 'payment_link' && flow.silent)
+            .flatMap(flow => [
+            ...catalog.offerings
+                .filter(offering => offering.url === null)
+                .map(offering => `flow '${flow.id}' is a silent payment link, so offering '${offering.id}' needs a url`),
+            ...(field || ids.length === 1
+                ? []
+                : [
+                    `flow '${flow.id}' is a silent payment link, so with several offerings a field must be marked "offering"`,
+                ]),
+        ]),
     ];
 }
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/contracts/config.d.ts

@@ -186,6 +186,7 @@ export declare const ToolsSchema: z.ZodObject<{
         }> & z.ZodType<"qualifying" | "nurturing" | "offered" | "prepared", "new" | "qualifying" | "nurturing" | "offered" | "prepared" | "link_sent", z.core.$ZodTypeInternals<"qualifying" | "nurturing" | "offered" | "prepared", "new" | "qualifying" | "nurturing" | "offered" | "prepared" | "link_sent">>>;
         offering: z.ZodOptional<z.ZodString>;
         settleSeconds: z.ZodOptional<z.ZodNumber>;
+        silent: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;

package/dist/contracts/config.js

@@ -315,8 +315,9 @@ export const ToolsSchema = z
         repeatable: z.boolean().optional(),
         /**
          * `payment_link`: performing it writes the funnel field to `link_sent`
-         * (specs/023). `opening`: the server sends it on the contact's first
-         * model turn, and the model never does (specs/032).
+         * (specs/023); with `silent`, the reply carries the link. `opening`:
+         * the server sends it on the contact's first model turn, and the
+         * model never does (specs/032).
          */
         role: z.enum(['payment_link', 'opening']).optional(),
         /**
@@ -338,9 +339,20 @@ export const ToolsSchema = z
          * (specs/030). Absent, it does not wait.
          */
         settleSeconds: z.number().int().min(0).max(MAX_SETTLE_SECONDS).optional(),
+        /**
+         * The flow sends the contact no message: it only records something
+         * in ManyChat, such as a tracking event. On the payment-link flow it
+         * means the reply carries the link (specs/023 § A silent payment
+         * flow leaves the link to the reply).
+         */
+        silent: z.boolean().optional(),
     }))
         .default([])
         .refine(uniqueIds, 'flow ids must be unique')
+        // Nothing plays, so there is nothing for the reply to wait for (specs/030).
+        .refine(flows => !flows.some(flow => flow.silent && flow.settleSeconds !== undefined), 'a "silent" flow may not have "settleSeconds"')
+        // The opening is the contact's first message from the tenant (specs/032).
+        .refine(flows => !flows.some(flow => flow.silent && flow.role === 'opening'), 'the "opening" flow may not be "silent"')
         .refine(flows => flows.filter(flow => flow.role === 'payment_link').length <= 1, 'only one flow may have role "payment_link"')
         // One payment flow serves every offering and branches on the offering
         // field inside ManyChat (specs/028 § One payment flow serves every offering).

package/package.json

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