manychat-ai-agent 0.26.0 → 0.26.1

package/dist/agent/tools/send-flow.js

@@ -0,0 +1,115 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { LINK_SENT, PREPARED } from "../../contracts/config.js";
+import { eventFor } from "./contact-actions.js";
+import { catalogOf, CONTACT_ASKED, idsOf, SENT_NOW, SILENT, silentResult, STAGED } from "./copy.js";
+import { stageIndex } from "./lookups.js";
+import { fitsOffering, NOT_PROSPECT } from "./turn.js";
+/** `send_flow`: the content flows not yet sent to the contact (specs/023, 028, 029, 032). */
+export function addSendFlow(turn, tools) {
+    const { config, stage, contact, options, funnel } = turn;
+    if (turn.unsent.length > 0) {
+        const flows = new Map(turn.unsent.map(flow => [flow.id, flow]));
+        // The enum holds every unsent flow, so one the agent makes available by
+        // setting the offering this turn can still be named; the description lists
+        // only those it can accept now.
+        const available = turn.unsent.filter(flow => fitsOffering(flow, turn.turnOffering()));
+        // With an offering known, an empty list means its content was all sent:
+        // told to set the offering, the model could switch it just to have something to
+        // send, or try a write the lock refuses.
+        const listing = available.length > 0
+            ? catalogOf(available)
+            : turn.turnOffering() === undefined
+                ? 'None yet: record the contact’s offering with set_field first.'
+                : 'None: everything for this contact’s offering has been sent.';
+        const sends = options.flows;
+        // The payment link waits for readiness unless the contact asked to pay
+        // (specs/032 § The payment link waits for readiness).
+        const gated = funnel !== undefined && turn.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}` +
+                (turn.unsent.some(flow => flow.silent) ? `\n${SILENT}` : '') +
+                (gated ? `\n${CONTACT_ASKED}` : ''),
+            inputSchema: gated
+                ? z.object({ flow: z.enum(idsOf(turn.unsent)), contactAsked: z.boolean().optional() })
+                : z.object({ flow: z.enum(idsOf(turn.unsent)) }),
+            execute: async (input) => {
+                if (turn.closed())
+                    return sends ? { sent: false, reason: 'not_prospect' } : NOT_PROSPECT;
+                const { flow } = input;
+                const entry = flows.get(flow);
+                // Another offering's content is refused, whatever the model names.
+                if (!fitsOffering(entry, turn.turnOffering()))
+                    return sends ? { sent: false } : { staged: false };
+                // Recorded only when it opened the gate, so the bypass rate counts
+                // bypasses, not every claim the model makes (specs/032).
+                const asked = entry.role === 'payment_link' &&
+                    input.contactAsked === true &&
+                    funnel !== undefined &&
+                    turn.stageFloor() < stageIndex(PREPARED);
+                if (entry.role === 'payment_link' &&
+                    funnel &&
+                    !asked &&
+                    turn.stageFloor() < stageIndex(PREPARED)) {
+                    return sends
+                        ? { sent: false, reason: 'not_prepared' }
+                        : { staged: false, reason: 'not_prepared' };
+                }
+                // The server, not the model, records that the link went out, and only
+                // once the flow itself has (specs/023 § The sale ends at the
+                // payment-link flow).
+                // Its event, if any, follows the write in turn (specs/027).
+                const event = funnel ? eventFor(config, contact, LINK_SENT) : undefined;
+                const followOn = entry.role === 'payment_link' && funnel
+                    ? {
+                        tool: 'set_field',
+                        id: funnel.id,
+                        field: funnel.field,
+                        value: LINK_SENT,
+                        ...(event ? { followOn: event } : {}),
+                    }
+                    : undefined;
+                const action = {
+                    tool: 'send_flow',
+                    id: flow,
+                    flowNs: entry.flowNs,
+                    ...(followOn ? { followOn } : {}),
+                    ...(asked ? { contactAsked: true } : {}),
+                };
+                // 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).
+                const link = entry.role === 'payment_link' && funnel !== undefined;
+                if (link)
+                    turn.linkStarting += 1;
+                try {
+                    if (options.beforeFlow)
+                        await options.beforeFlow();
+                }
+                finally {
+                    // From here the reserved entry counts while the link is in flight.
+                    if (link)
+                        turn.linkStarting -= 1;
+                }
+                // Sent now, so the reply written after it follows it (specs/029). A
+                // payment link takes the turn's staged stage writes ahead of it, so
+                // its `link_sent` is the last stage ManyChat is given.
+                const first = entry.role === 'payment_link' && funnel
+                    ? stage.staged.filter(staged => staged.tool === 'set_field' && staged.id === funnel.id)
+                    : [];
+                const sent = await stage.send(action, sends, first);
+                if (sent === undefined)
+                    return { sent: false, reason: 'over the per-turn limit' };
+                return sent ? { sent, ...silent } : { sent };
+            },
+        });
+    }
+}

package/dist/agent/tools/set-field.d.ts

@@ -0,0 +1,7 @@
+import { type ToolSet } from 'ai';
+import type { ToolTurn } from './turn.ts';
+/**
+ * `set_field`: the tenant's enum fields, the funnel, the offering and intent
+ * among them (specs/012, 023, 028, 032, 034, 045).
+ */
+export declare function addSetField(turn: ToolTurn, tools: ToolSet): void;

package/dist/agent/tools/set-field.js

@@ -0,0 +1,142 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { LINK_SENT, PROSPECT } from "../../contracts/config.js";
+import { eventFor } from "./contact-actions.js";
+import { idsOf, STAGED } from "./copy.js";
+import { OFFERING_LOCKED_FROM, openingFlow, stageIndex } from "./lookups.js";
+import { fitsOffering, NOT_PROSPECT } from "./turn.js";
+/**
+ * `set_field`: the tenant's enum fields, the funnel, the offering and intent
+ * among them (specs/012, 023, 028, 032, 034, 045).
+ */
+export function addSetField(turn, tools) {
+    const { config, stage, contact, options, funnel, intent, offering } = turn;
+    if (config.fields.length > 0) {
+        // `link_sent` is the server's to write, so the model cannot name it.
+        const offered = config.fields.map(field => field.funnel
+            ? { ...field, values: field.values.filter(value => value !== LINK_SENT) }
+            : field);
+        const fields = new Map(offered.map(field => [field.id, field]));
+        const values = [...new Set(offered.flatMap(field => field.values))];
+        const listing = offered
+            .map(field => `- ${field.id} (one of: ${field.values.join(', ')}): ${field.description}`)
+            .join('\n');
+        /**
+         * The flow tied to a stage the model just moved the contact to, sent as a
+         * flow the model calls is (specs/032 § A stage move can carry a flow):
+         * once per contact, only for the turn's offering, and only for the stage
+         * written, never one skipped.
+         */
+        const overCap = (id) => ({ flowDropped: id, reason: 'over the per-turn limit' });
+        const sendTied = async (value) => {
+            const tied = config.flows.find(flow => flow.onStage === value);
+            if (!tied || !fitsOffering(tied, turn.turnOffering()))
+                return {};
+            if (!tied.repeatable && contact.sentFlows.has(tied.id))
+                return {};
+            if (stage.sent.some(sent => sent.action.tool === 'send_flow' && sent.action.id === tied.id)) {
+                return {};
+            }
+            const action = {
+                tool: 'send_flow',
+                id: tied.id,
+                flowNs: tied.flowNs,
+                origin: 'stage',
+            };
+            if (!options.flows) {
+                // `stage` refuses only over the cap; a repeat is reported as staged.
+                return stage.stage(action) ? { flowStaged: tied.id } : overCap(tied.id);
+            }
+            if (options.beforeFlow)
+                await options.beforeFlow();
+            const sent = await stage.send(action, options.flows);
+            // Dropped over the cap is not refused by ManyChat: the model may still
+            // send the flow itself on a later turn (specs/032).
+            if (sent === undefined)
+                return overCap(tied.id);
+            return sent ? { flowSent: tied.id } : { flowRefused: tied.id };
+        };
+        tools.set_field = tool({
+            description: `Record one of these choices on the contact.\n${listing}\n${STAGED}`,
+            // Never free text (specs/012 § Free-text field values are refused). The
+            // enum covers every field's values; the refinement holds each value to
+            // its own field.
+            inputSchema: z
+                .object({ field: z.enum(idsOf(config.fields)), value: z.enum(values) })
+                .refine(input => fields.get(input.field).values.includes(input.value), {
+                message: 'value is not one of this field’s configured values',
+                path: ['value'],
+            }),
+            execute: async ({ field, value }) => {
+                if (field === intent?.id) {
+                    // Intent moves one way, and `prospect` is final (specs/034 § Intent
+                    // is a field the model records).
+                    const before = turn.turnIntent();
+                    if (before === PROSPECT && value !== PROSPECT)
+                        return { staged: false };
+                    const staged = stage.stage({
+                        tool: 'set_field',
+                        id: field,
+                        field: fields.get(field).field,
+                        value,
+                    });
+                    // The opening belongs to the turn that first stages `prospect`, and
+                    // the result says so, since the server could not know before the
+                    // loop ran (specs/034 § The opening waits for a prospect).
+                    const opening = openingFlow(config);
+                    return staged &&
+                        value === PROSPECT &&
+                        before !== PROSPECT &&
+                        contact.openingDue &&
+                        opening
+                        ? { staged, openingQueued: { flow: opening.id, description: opening.description } }
+                        : { staged };
+                }
+                if (turn.closed())
+                    return NOT_PROSPECT;
+                // The stage only moves forward (specs/023 § The funnel is a field the
+                // agent moves).
+                const floor = turn.stageFloor();
+                if (field === funnel?.id && stageIndex(value) < floor)
+                    return { staged: false };
+                if (field !== offering?.id) {
+                    // The server's measurement of the write, never the model's choice
+                    // (specs/027 § An event is a measurement).
+                    const event = field === funnel?.id ? eventFor(config, contact, value) : undefined;
+                    const staged = stage.stage({
+                        tool: 'set_field',
+                        id: field,
+                        field: fields.get(field).field,
+                        value,
+                        ...(event ? { followOn: event } : {}),
+                    });
+                    const moved = field === funnel?.id && staged && stageIndex(value) > floor;
+                    return moved ? { staged, ...(await sendTied(value)) } : { staged };
+                }
+                // Once an offering and its price have been put to the contact, a person
+                // decides a switch (specs/028 § The offering may change until the offer),
+                // unless the tenant keeps it open (specs/045).
+                if (!offering?.switchable && turn.stageFloor() >= stageIndex(OFFERING_LOCKED_FROM)) {
+                    return { staged: false };
+                }
+                const before = turn.turnOffering();
+                const staged = stage.stage({
+                    tool: 'set_field',
+                    id: field,
+                    field: fields.get(field).field,
+                    value,
+                    offering: true,
+                });
+                if (!staged)
+                    return { staged };
+                // Available in the same turn, and said so, since the send_flow
+                // description was written before the offering was known.
+                const opened = turn.unsent.filter(flow => flow.offering === value && !fitsOffering(flow, before));
+                return {
+                    staged,
+                    flowsAvailable: opened.map(flow => ({ flow: flow.id, description: flow.description })),
+                };
+            },
+        });
+    }
+}

package/dist/agent/tools/stage.d.ts

@@ -0,0 +1,92 @@
+import type { ActionRecord, ActionStatus, PerformableAction, StagedAction } from '../../contracts/agent.ts';
+import type { FlowSends, SendFlowAction } from '../flows.ts';
+/**
+ * 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[];
+}

package/dist/agent/tools/stage.js

@@ -0,0 +1,176 @@
+/**
+ * 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 const MAX_ACTIONS_PER_TURN = 8;
+/** `send_flow intro_course_brochure`, `set_field preferred_shift=evening`. */
+export function describeAction(action) {
+    return action.value === undefined
+        ? `${action.tool} ${action.id}`
+        : `${action.tool} ${action.id}=${action.value}`;
+}
+/**
+ * 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 function recordOf(action, status, error) {
+    return {
+        tool: action.tool,
+        id: action.id,
+        ...(action.tool === 'set_field' ? { value: action.value } : {}),
+        ...(action.tool === 'write_note' ? { length: action.text.length } : {}),
+        status,
+        ...(error === undefined ? {} : { error }),
+        ...(action.tool === 'send_flow' && action.origin ? { origin: action.origin } : {}),
+        ...(action.tool === 'send_flow' && action.contactAsked ? { contactAsked: true } : {}),
+    };
+}
+/**
+ * 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 class ActionStage {
+    accepted = [];
+    overCap = [];
+    sentNow = [];
+    /** Staged and sent entries in the order the model made them, for the record. */
+    order = [];
+    /** Sends the cap does not count: the opening flow is the server's (specs/032). */
+    uncapped = 0;
+    /**
+     * 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) {
+        const key = JSON.stringify(action);
+        const same = (existing) => JSON.stringify(existing) === key;
+        if (this.accepted.some(same))
+            return true;
+        if (this.full) {
+            if (!this.overCap.some(same))
+                this.overCap.push(action);
+            return false;
+        }
+        this.accepted.push(action);
+        this.order.push(action);
+        return true;
+    }
+    /** A flow sent this turn counts against the cap as a staged action does. */
+    get full() {
+        return this.accepted.length + this.sentNow.length - this.uncapped >= MAX_ACTIONS_PER_TURN;
+    }
+    /**
+     * 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.
+     */
+    async send(action, sends, first = [], 
+    /** Not counted against the cap: the server's opening flow (specs/032). */
+    options = {}) {
+        const earlier = this.sentNow.find(entry => entry.action.tool === 'send_flow' && entry.action.id === action.id);
+        if (earlier) {
+            // A repeat made while the first request is in flight (parallel calls in
+            // one step) gets its real outcome, not the placeholder.
+            await earlier.done;
+            return earlier.records[0]?.status === 'performed';
+        }
+        if (!options.uncapped && this.full) {
+            if (!this.overCap.some(entry => entry.tool === 'send_flow' && entry.id === action.id)) {
+                this.overCap.push(action);
+            }
+            return undefined;
+        }
+        // Reserved before the request, so a second call made while it is in
+        // flight neither sends the flow twice nor slips past the cap. Recorded as
+        // failed until ManyChat answers: a turn that ends while the request is in
+        // flight cannot say it went out.
+        const reserve = (entryAction) => ({
+            action: entryAction,
+            records: [recordOf(entryAction, 'failed', 'no answer before the turn ended')],
+            done: Promise.resolve(),
+            pending: true,
+        });
+        const ahead = first.filter(staged => this.accepted.includes(staged)).map(reserve);
+        for (const entry of ahead) {
+            const at = this.accepted.indexOf(entry.action);
+            this.accepted.splice(at, 1);
+            this.sentNow.push(entry);
+            this.order[this.order.indexOf(entry.action)] = { sent: this.sentNow.length - 1 };
+        }
+        const entry = reserve(action);
+        if (options.uncapped)
+            this.uncapped += 1;
+        this.sentNow.push(entry);
+        this.order.push({ sent: this.sentNow.length - 1 });
+        const done = sends.send([...ahead.map(staged => staged.action), action]).then(groups => {
+            [...ahead, entry].forEach((sent, index) => {
+                sent.records = groups[index] ?? sent.records;
+                sent.pending = false;
+            });
+        });
+        for (const sent of [...ahead, entry])
+            sent.done = done;
+        await done;
+        return entry.records[0]?.status === 'performed';
+    }
+    /**
+     * 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.
+     */
+    async settled() {
+        await Promise.all(this.sentNow.map(entry => entry.done));
+    }
+    /** Actions sent this turn, whatever became of them. */
+    get sent() {
+        return this.sentNow;
+    }
+    /** In the order the model staged them, which is the order they are performed in. */
+    get staged() {
+        return this.accepted;
+    }
+    get dropped() {
+        return this.overCap;
+    }
+    /**
+     * 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) {
+        return keepNotes
+            ? this.accepted.filter(action => action.tool === 'write_note' && action.onEscalation)
+            : [];
+    }
+    /**
+     * 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, kept = []) {
+        // A flow already sent keeps its outcome: an escalation cannot recall it.
+        return [
+            ...this.order.flatMap(entry => 'sent' in entry
+                ? this.sentNow[entry.sent].records
+                : [recordOf(entry, kept.includes(entry) ? 'staged' : status)]),
+            ...this.overCap.map(action => recordOf(action, 'dropped_over_cap')),
+        ];
+    }
+}

package/dist/agent/tools/tags.d.ts

@@ -0,0 +1,4 @@
+import { type ToolSet } from 'ai';
+import type { ToolTurn } from './turn.ts';
+/** `add_tag` and `remove_tag`: the tenant's tags (specs/012). */
+export declare function addTagTools(turn: ToolTurn, tools: ToolSet): void;

package/dist/agent/tools/tags.js

@@ -0,0 +1,26 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { catalogOf, idsOf, STAGED } from "./copy.js";
+import { NOT_PROSPECT } from "./turn.js";
+/** `add_tag` and `remove_tag`: the tenant's tags (specs/012). */
+export function addTagTools(turn, tools) {
+    const { config, stage } = turn;
+    if (config.tags.length > 0) {
+        const tags = new Map(config.tags.map(entry => [entry.id, entry]));
+        const input = z.object({ tag: z.enum(idsOf(config.tags)) });
+        tools.add_tag = tool({
+            description: `Add one of these tags to the contact.\n${catalogOf(config.tags)}\n${STAGED}`,
+            inputSchema: input,
+            execute: ({ tag }) => turn.closed()
+                ? NOT_PROSPECT
+                : { staged: stage.stage({ tool: 'add_tag', id: tag, tag: tags.get(tag).tag }) },
+        });
+        tools.remove_tag = tool({
+            description: `Remove one of these tags from the contact.\n${catalogOf(config.tags)}\n${STAGED}`,
+            inputSchema: input,
+            execute: ({ tag }) => turn.closed()
+                ? NOT_PROSPECT
+                : { staged: stage.stage({ tool: 'remove_tag', id: tag, tag: tags.get(tag).tag }) },
+        });
+    }
+}

package/dist/agent/tools/turn.d.ts

@@ -0,0 +1,93 @@
+import type { Tools } from '../../contracts/config.ts';
+import type { Plugins } from '../../plugins/plugins.ts';
+import type { PluginReads } from '../../plugins/reads.ts';
+import type { FlowSends } from '../flows.ts';
+import type { ContactActions } from './contact-actions.ts';
+import { funnelField, intentField, offeringField } from './lookups.ts';
+import type { Intent } from './lookups.ts';
+import type { ActionStage } from './stage.ts';
+export interface BuildToolsOptions {
+    /**
+     * A nudge turn is offered no `schedule_nudge`, so a nudge never schedules
+     * another (specs/025).
+     */
+    nudgeTurn?: boolean;
+    /** Sends a flow when it is called instead of staging it (specs/029). */
+    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;
+}
+/** What a sales tool returns while the contact is not a prospect (specs/034). */
+export declare const NOT_PROSPECT: {
+    readonly staged: false;
+    readonly reason: "not_prospect";
+};
+/** Whether a flow serves the turn's offering: its own, or every one (specs/028). */
+export declare const fitsOffering: (flow: {
+    offering?: string | undefined;
+}, current: string | undefined) => boolean;
+/**
+ * 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 declare class ToolTurn {
+    readonly config: Tools;
+    readonly stage: ActionStage;
+    readonly contact: ContactActions;
+    readonly options: BuildToolsOptions;
+    readonly funnel: ReturnType<typeof funnelField>;
+    readonly intent: ReturnType<typeof intentField>;
+    readonly offering: ReturnType<typeof offeringField>;
+    /**
+     * 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).
+     */
+    readonly unsent: Tools['flows'];
+    /**
+     * 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: number;
+    constructor(config: Tools, stage: ActionStage, contact: ContactActions, options: BuildToolsOptions);
+    /**
+     * 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(): Intent | undefined;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): string | undefined;
+    /**
+     * 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(): number;
+}