manychat-ai-agent 0.26.0 → 0.26.1

package/dist/agent/tools/turn.js

@@ -0,0 +1,93 @@
+import { LINK_SENT, PROSPECT } from "../../contracts/config.js";
+import { funnelField, intentField, offeringField, stageIndex } from "./lookups.js";
+/** What a sales tool returns while the contact is not a prospect (specs/034). */
+export const NOT_PROSPECT = { staged: false, reason: 'not_prospect' };
+/** Whether a flow serves the turn's offering: its own, or every one (specs/028). */
+export const fitsOffering = (flow, current) => flow.offering === undefined || flow.offering === current;
+/**
+ * What every tool of one turn reads as it runs: the gate on intent, the
+ * turn's offering and the floor under the funnel stage. Read from the stage
+ * each time, so a write staged by one tool is seen by the next, in the same
+ * step included.
+ */
+export class ToolTurn {
+    config;
+    stage;
+    contact;
+    options;
+    funnel;
+    intent;
+    offering;
+    /**
+     * A flow already sent to this contact is not offered again, so a repeat is
+     * unrepresentable rather than discouraged (specs/023 § Every content flow
+     * is a leaf, sent once). An offering change does not bring one back
+     * (specs/028). The opening flow is the server's to send, never the model's
+     * (specs/032).
+     */
+    unsent;
+    /**
+     * A payment link marked here before any await on its way out, so a call
+     * beside it in the same step already sees it (specs/029, specs/032).
+     */
+    linkStarting = 0;
+    constructor(config, stage, contact, options) {
+        this.config = config;
+        this.stage = stage;
+        this.contact = contact;
+        this.options = options;
+        this.funnel = funnelField(config);
+        this.intent = intentField(config);
+        this.offering = offeringField(config);
+        this.unsent = config.flows.filter(flow => flow.role !== 'opening' && (flow.repeatable || !contact.sentFlows.has(flow.id)));
+    }
+    /**
+     * The contact's intent as the server knows it, a write staged earlier this
+     * turn included, so a first message can be recorded as a prospect and sold
+     * to in one turn (specs/034 § Until intent is prospect, the sale's tools
+     * refuse).
+     */
+    turnIntent() {
+        const staged = this.stage.staged.findLast((action) => action.tool === 'set_field' && action.id === this.intent?.id);
+        return staged?.value ?? this.contact.intent;
+    }
+    /**
+     * Refused rather than removed from the enums: removing them would rule out
+     * the same-turn unlock. A refusal makes no request and takes no slot of the
+     * cap (specs/034).
+     */
+    closed() {
+        return this.intent !== undefined && this.turnIntent() !== PROSPECT;
+    }
+    /**
+     * The turn's offering: one staged on the offering field earlier in this
+     * turn, or else the contact's (specs/028 § A flow belongs to one offering or
+     * to all).
+     */
+    turnOffering() {
+        const staged = this.stage.staged.findLast((action) => action.tool === 'set_field' && action.offering === true);
+        return staged?.value ?? this.contact.offering;
+    }
+    /**
+     * The earliest stage a write may name: the last one performed for this
+     * contact, or a later one already staged this turn. Parallel calls in one
+     * step must not walk a lead back any more than a later turn may.
+     */
+    stageFloor() {
+        const { stage, contact, funnel } = this;
+        return Math.max(stageIndex(contact.funnelStage), this.linkStarting > 0 ? stageIndex(LINK_SENT) : -1, ...stage.staged.map(action => action.tool === 'set_field' && action.id === funnel?.id ? stageIndex(action.value) : -1), 
+        // Writes already made this turn, a payment link's `link_sent` among
+        // them (specs/029), so nothing staged after can walk the stage back.
+        ...stage.sent.flatMap(sent => sent.records.map(record => record.tool === 'set_field' && record.id === funnel?.id && record.status === 'performed'
+            ? stageIndex(record.value)
+            : -1)), 
+        // A payment link still in flight counts at the stage it is about to
+        // write: a call in the same step runs while it waits (the SDK starts a
+        // step's calls together), and would otherwise stage a lower write
+        // that lands after `link_sent`. If the link then fails, the turn has
+        // at most one step left.
+        ...stage.sent.map(sent => sent.pending && sent.action.tool === 'send_flow' && sent.action.followOn?.id === funnel?.id
+            ? stageIndex(sent.action.followOn?.value)
+            : -1));
+    }
+}

package/dist/agent/tools.d.ts

@@ -1,267 +1,12 @@
-import { type ToolSet } from 'ai';
-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';
-import type { Plugins } from '../plugins/plugins.ts';
-import type { PluginReads } from '../plugins/reads.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
- * § The loop grows to four steps and eight actions). Chosen, not measured.
- */
-export declare const MAX_STEPS = 4;
-/**
- * Bounds the burst one turn can put through the ManyChat rate limiter, one
- * request per action. Eight fit a flow, a funnel stage, two qualification
- * fields, a tag and three notes (specs/024). Chosen, not measured.
- */
-export declare const MAX_ACTIONS_PER_TURN = 8;
-/** `send_flow intro_course_brochure`, `set_field preferred_shift=evening`. */
-export declare function describeAction(action: {
-    tool: string;
-    id: string;
-    value?: string | undefined;
-}): string;
-/**
- * The entry recorded on the turn: ids and values, never ManyChat names. A
- * note is recorded by its length, never its text (specs/024 § Note text never
- * reaches the record or the logs).
- */
-export declare function recordOf(action: PerformableAction, status: ActionStatus, error?: string): ActionRecord;
-/**
- * Everything the model staged on one turn. A tool's `execute` writes here and
- * nothing else: no ManyChat write is made inside the model call, because at
- * that point the model has not decided whether to escalate and the guardrails
- * have not run (ADR-0010). The exception is a flow on an inbound turn, sent
- * when called so the reply can follow it (specs/029, ADR-0019); it is kept
- * here with what became of it, in call order.
- *
- * Created by the caller rather than the runner, so what was staged is still
- * known when the model call is aborted and never returns.
- */
-export declare class ActionStage {
-    private readonly accepted;
-    private readonly overCap;
-    private readonly sentNow;
-    /** Staged and sent entries in the order the model made them, for the record. */
-    private readonly order;
-    /** Sends the cap does not count: the opening flow is the server's (specs/032). */
-    private uncapped;
-    /**
-     * Whether the action is staged. A repeat of one already staged is. Compared
-     * whole rather than by record, since two notes of one length differ.
-     */
-    stage(action: StagedAction): boolean;
-    /** A flow sent this turn counts against the cap as a staged action does. */
-    private get full();
-    /**
-     * Sends a flow now (specs/029). Returns whether ManyChat accepted it, or
-     * `undefined` when it is over the cap and was not sent. A flow already sent
-     * this turn is not sent again; its first outcome stands.
-     *
-     * `first` are actions already staged that must reach ManyChat before the
-     * flow: a payment link's `link_sent` would otherwise be overwritten by an
-     * earlier funnel write performed after the reply (specs/029 § A payment link
-     * takes the turn's stage writes with it). They are sent ahead of it, keep
-     * their place in the record, and are no longer staged.
-     */
-    send(action: SendFlowAction, sends: FlowSends, first?: readonly StagedAction[], 
-    /** Not counted against the cap: the server's opening flow (specs/032). */
-    options?: {
-        uncapped?: boolean;
-    }): Promise<boolean | undefined>;
-    /**
-     * Resolves once every send started this turn has its answer. A call aborted
-     * while a request is in flight does not stop the request, so the record waits
-     * for it rather than keeping the placeholder (specs/029). Bounded by the
-     * client's request timeout.
-     */
-    settled(): Promise<void>;
-    /** Actions sent this turn, whatever became of them. */
-    get sent(): readonly {
-        action: StagedAction;
-        records: readonly ActionRecord[];
-        pending: boolean;
-    }[];
-    /** In the order the model staged them, which is the order they are performed in. */
-    get staged(): readonly StagedAction[];
-    get dropped(): readonly StagedAction[];
-    /**
-     * What an escalated turn still performs: the notes marked `onEscalation`,
-     * and only when the model or the confidence threshold escalated (specs/024
-     * § A handoff summary survives the escalation it describes).
-     */
-    survivors(keepNotes: boolean): StagedAction[];
-    /**
-     * The turn's record before anything is performed: every accepted action
-     * with `status`, then those dropped over the cap. On an escalated turn
-     * (`discarded`), an action in `kept` is recorded `staged` instead, since it
-     * will still be performed.
-     */
-    records(status: 'staged' | 'discarded', kept?: readonly StagedAction[]): ActionRecord[];
-}
-/** The field the agent's position in the sale is kept in, if the tenant marked one (specs/023). */
-export declare function funnelField(config: Tools): {
-    id: string;
-    field: string;
-    values: string[];
-    description: string;
-    funnel?: boolean | undefined;
-    offering?: boolean | undefined;
-    switchable?: boolean | undefined;
-    intent?: boolean | undefined;
-} | undefined;
-/** The flow that ends the sale, if the tenant marked one (specs/023). */
-export declare function paymentLinkFlow(config: Tools): {
-    id: string;
-    flowNs: string;
-    description: string;
-    repeatable?: boolean | undefined;
-    role?: "payment_link" | "opening" | undefined;
-    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;
-    flowNs: string;
-    description: string;
-    repeatable?: boolean | undefined;
-    role?: "payment_link" | "opening" | undefined;
-    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): {
-    id: string;
-    field: string;
-    values: string[];
-    description: string;
-    funnel?: boolean | undefined;
-    offering?: boolean | undefined;
-    switchable?: boolean | undefined;
-    intent?: boolean | undefined;
-} | undefined;
-/** The field the contact's intent is kept in, if the tenant marked one (specs/034). */
-export declare function intentField(config: Tools): {
-    id: string;
-    field: string;
-    values: string[];
-    description: string;
-    funnel?: boolean | undefined;
-    offering?: boolean | undefined;
-    switchable?: boolean | undefined;
-    intent?: boolean | undefined;
-} | undefined;
-export type Intent = (typeof INTENT_VALUES)[number];
-/**
- * Whether the turn staged a write of `prospect`, which makes it the turn the
- * opening belongs to (specs/034 § The opening waits for a prospect).
- */
-export declare function stagesProspect(stage: ActionStage, config: Tools): boolean;
-/**
- * The offering a request presented, if it is one: a value of the offering
- * field. Empty, unrendered (`{{offering}}`) or unknown is no offering at all,
- * never a guess (specs/028 § The server learns the offering from the inbound
- * request).
- */
-export declare function knownOffering(raw: string | null | undefined, config: Tools): string | undefined;
-export interface ContactActions {
-    /** Flows performed for the contact within the history window. */
-    sentFlows: ReadonlySet<string>;
-    /** The funnel stage last recorded as performed for the contact, if any. */
-    funnelStage?: string | undefined;
-    /**
-     * The contact's offering as the turn starts: the request's, or else the
-     * one the conversation keeps (specs/028). Not read from the actions.
-     */
-    offering?: string | undefined;
-    /** The offering the conversation held before the request changed it, if it did. */
-    offeringChangedFrom?: string | undefined;
-    /**
-     * The contact's intent as the server knows it: the last performed write,
-     * or `prospect` by the rollout rule. Absent is unknown (specs/034).
-     */
-    intent?: Intent | undefined;
-    /**
-     * The contact has had the opening, or a turn that staged `prospect`, so
-     * the opening is never sent again (specs/034 § The opening waits for a
-     * prospect).
-     */
-    openingSpent?: boolean | undefined;
-    /**
-     * The opening goes out on this turn if it stages `prospect` and does not
-     * forfeit it by escalating (specs/034 § The opening waits for a prospect).
-     */
-    openingDue?: boolean | undefined;
-    /**
-     * The offering a bound request stored and the agent did not write: the
-     * contact arrived through its advert (specs/034 § What counts as prospect
-     * intent).
-     */
-    advertOffering?: string | undefined;
-}
-export declare const NO_CONTACT_ACTIONS: ContactActions;
-/**
- * Folds a contact's agent turns, oldest first, into `ContactActions`.
- *
- * Flows count only inside the history window (specs/018): a contact back
- * after it starts clean, as their history does. The stage counts however old,
- * because it only ever moves forward, and so do intent and the opening.
- */
-export declare function contactActionsFrom(turns: readonly {
-    createdAt: Date;
-    actions: readonly ActionRecord[] | null;
-}[], config: Tools, since: Date): ContactActions;
-/**
- * The tools for one turn, or undefined when `tools.json` configures none.
- *
- * Each parameter is an enum of the configured ids, so the model can only name
- * something the tenant set up (C3), and no tool takes a subscriber: the action
- * lands on whoever the turn belongs to (C4, C5). A tool whose list is empty is
- * not offered at all.
- */
-export declare function buildTools(config: Tools, stage: ActionStage, contact?: ContactActions, 
-/** The turn's own contact, readable only on a turn that reads history (specs/024). */
-reads?: ContactReads, 
-/**
- * A nudge turn is offered no `schedule_nudge`, so a nudge never schedules
- * another (specs/025). `flows`, when given, sends a flow when it is called
- * instead of staging it (specs/029).
- */
-options?: {
-    nudgeTurn?: boolean;
-    flows?: FlowSends | undefined;
-    /**
-     * Runs before the turn's first flow goes out: on the prospect turn it
-     * sends the opening, so no content reaches the contact ahead of it
-     * (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;
-    /**
-     * The turn's plugin reads. Absent, no read tool is offered: as for
-     * `get_contact`, only a turn that reads history may read (specs/039).
-     */
-    pluginReads?: PluginReads | undefined;
-}): ToolSet | undefined;
+ * The tools the model may call on a turn (specs/012), and the stage that
+ * holds what it chose (ADR-0010). Split across `tools/` by concern; this
+ * file is the one place they are imported from.
+ */
+export { MAX_STEPS, buildTools } from './tools/build.ts';
+export type { BuildToolsOptions } from './tools/turn.ts';
+export { MAX_ACTIONS_PER_TURN, ActionStage, describeAction, recordOf } from './tools/stage.ts';
+export { funnelField, intentField, knownOffering, offeringField, openingFlow, paymentLinkFlow, silentPaymentLink, stagesProspect, } from './tools/lookups.ts';
+export type { Intent } from './tools/lookups.ts';
+export { NO_CONTACT_ACTIONS, contactActionsFrom } from './tools/contact-actions.ts';
+export type { ContactActions } from './tools/contact-actions.ts';