@flow-engineer/flow 0.2.2 → 0.2.3

package/dist/flow-messaging/src/client.d.ts

@@ -28,8 +28,8 @@ export declare class Client {
     get<T>(path: string): Promise<T>;
     /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
     download(fileId: string): Promise<Uint8Array>;
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post<T>(path: string, body: unknown, tries?: number): Promise<T>;
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post<T>(path: string, body: unknown, tries?: number, idempotencyKey?: string): Promise<T>;
     private request;
 }
 /**

package/dist/flow-messaging/src/client.js

@@ -66,9 +66,9 @@ export class Client {
             throw await errorOf(response);
         return new Uint8Array(await response.arrayBuffer());
     }
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post(path, body, tries = TRIES) {
-        return this.request("POST", path, body, randomUUID(), tries);
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post(path, body, tries = TRIES, idempotencyKey = randomUUID()) {
+        return this.request("POST", path, body, idempotencyKey, tries);
     }
     async request(method, path, body, idempotencyKey, tries = TRIES) {
         if (!this.apiKey)

package/dist/flow-messaging/src/index.js

@@ -97,16 +97,16 @@ export function flowMessaging(options = {}) {
         return { phone: to.startsWith("+") ? to : `+${to}` };
     }
     /** One message: into the person's conversation, or a new one from the channel's sender. */
-    async function send(route, to, content, replyTo, about = replyTo) {
+    async function send(route, to, content, replyTo, about = replyTo, idempotencyKey) {
         try {
             const conversation = await conversationFor(route.name, to, about);
             let sent;
             if (conversation)
-                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) });
+                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) }, undefined, idempotencyKey);
             else {
                 if (!route.sender)
                     throw new Error(`no conversation with them on ${route.name} yet, and no sender to start one (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
-                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content });
+                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content }, undefined, idempotencyKey);
             }
             flowConversation.set(key(route.name, to), sent.conversation);
         }
@@ -176,19 +176,20 @@ export function flowMessaging(options = {}) {
         return {
             sendMessage: async (to, message) => {
                 const [first, ...rest] = contents(route.kind, message);
-                await send(route, to, first, message.replyTo);
-                for (const next of rest)
-                    await send(route, to, next);
+                const key = message.idempotencyKey;
+                await send(route, to, first, message.replyTo, message.replyTo, key);
+                for (const [i, next] of rest.entries())
+                    await send(route, to, next, undefined, undefined, key && `${key}:${i + 1}`);
             },
             react: (to, messageId, emoji) => send(route, to, { type: "reaction", message_id: messageId, emoji }, undefined, messageId),
             typing: (to, on) => courtesy(route, to, "typing", { state: on ? "on" : "off" }),
             markRead: (to, messageIds) => courtesy(route, to, "read", { up_to: messageIds.at(-1) }, messageIds.at(-1)),
-            sendTemplate: async (to, wanted) => {
+            sendTemplate: async (to, wanted, idempotencyKey) => {
                 if (!route.sender)
                     throw new Error(`a template needs the channel's sender (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
                 const found = await template(route.sender, wanted);
                 const params = templateParams(wanted);
-                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) });
+                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) }, undefined, undefined, idempotencyKey);
             },
         };
     }
@@ -232,6 +233,7 @@ export function flowMessaging(options = {}) {
                             ...(outbound.buttons && info.buttons ? { buttons: outbound.buttons } : {}),
                             ...(outbound.link && info.linkButton ? { link: outbound.link } : {}),
                             ...(outbound.image && info.images ? { image: outbound.image } : {}),
+                            ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
                         });
                     case "reaction":
                         return p.react(to, outbound.messageId, outbound.emoji);

package/dist/src/channels.d.ts

@@ -76,6 +76,8 @@ export interface Message {
     image?: {
         url: string;
     };
+    /** Given for a send the business starts (a nudge, a scheduled text): the same in every process, so a provider that takes one sends it once. */
+    idempotencyKey?: string;
 }
 export interface WhatsAppProvider {
     sendMessage(to: string, message: Message): Promise<void>;
@@ -90,12 +92,10 @@ export interface WhatsAppProvider {
     react?(to: string, messageId: string, emoji: string): Promise<void>;
     typing?(to: string, on: boolean): Promise<void>;
     markRead?(to: string, messageIds: string[]): Promise<void>;
-    sendTemplate?(to: string, template: Template): Promise<void>;
+    sendTemplate?(to: string, template: Template, idempotencyKey?: string): Promise<void>;
 }
 export interface SmsProvider {
-    sendMessage(to: string, message: {
-        text: string;
-    }): Promise<void>;
+    sendMessage(to: string, message: Pick<Message, "text" | "idempotencyKey">): Promise<void>;
 }
 /** Your own UI. `message` carries the text, any buttons, and your params by name. */
 export interface CustomUIProvider {

package/dist/src/channels.js

@@ -93,8 +93,8 @@ export function whatsapp(provider, options = {}) {
                 case "template": {
                     if (!provider.sendTemplate || off.has("templates"))
                         throw new Error("this WhatsApp provider sends no templates");
-                    const { type: _type, ...template } = outbound;
-                    return provider.sendTemplate(to, template);
+                    const { type: _type, idempotencyKey, ...template } = outbound;
+                    return provider.sendTemplate(to, template, idempotencyKey);
                 }
                 case "status":
                     return;
@@ -112,7 +112,7 @@ export function sms(provider, options = {}) {
         phone: true,
         send: (to, outbound) => {
             if (outbound.type === "message")
-                return provider.sendMessage(to, { text: outbound.text });
+                return provider.sendMessage(to, { text: outbound.text, ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}) });
             if (outbound.type === "template")
                 throw new Error("SMS has no templates");
             // Reactions, typing, read receipts and status do not exist on SMS.
@@ -159,6 +159,7 @@ function message(outbound) {
         ...(outbound.list ? { list: outbound.list } : {}),
         ...(outbound.link ? { link: outbound.link } : {}),
         ...(outbound.image ? { image: outbound.image } : {}),
+        ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
     };
 }
 /**

package/dist/src/conversation.d.ts

@@ -268,6 +268,7 @@ export declare class Conversation {
     private send;
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     private sendDirect;
+    private directSettled;
     /**
      * The history the model is sent: all of it while it fits the budget, else the latest entries
      * that do, from the start of one (never between a call and its result), after a line that says

package/dist/src/conversation.js

@@ -443,7 +443,7 @@ export class Conversation {
         }
         else if (row.kind === "schedule") {
             if (p.fixed)
-                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run });
+                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run, schedule: p.schedule });
             else
                 this.notes.push({ text: p.text, inbox: row.id, owed: { run: p.run, mode: p.mode, channel: p.channel } });
         }
@@ -573,8 +573,14 @@ export class Conversation {
             this.note(`[Chinwag] ${task.tool} (${task.taskId}) was still running in the background when the agent restarted. It may or may not have finished; check before telling them it is done.`);
             this.persist(() => store.removeTask(this.id, task.taskId));
         }
-        for (const row of await store.openInbox(this.id))
-            this.enqueue(row);
+        for (const row of await store.openInbox(this.id)) {
+            // Already in the history (its row was not marked done): answered, so not answered again.
+            const p = row.payload;
+            if (row.kind === "message" && this.messageIds.get(p.id) === p.channel)
+                this.persist(() => store.doneInbox([row.id]));
+            else
+                this.enqueue(row);
+        }
         const row = await store.conversation(this.id);
         this.resumeTurn = row?.turnOpen === true;
         if ((this.resumeTurn || this.hasWork()) && !this.running)
@@ -1136,6 +1142,12 @@ export class Conversation {
     }
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     async sendDirect(d) {
+        // Settled already (by an earlier process, or another one running beside this): never sent twice.
+        if (await this.directSettled(d)) {
+            if (d.inbox !== undefined)
+                this.persist(() => this.settings.store.doneInbox([d.inbox]));
+            return;
+        }
         const settle = (status, reason) => {
             this.settle(d, status, reason);
             this.flush([d]);
@@ -1163,7 +1175,9 @@ export class Conversation {
         }
         if (covered)
             return settle("dropped", `no-contact rule ${covered.id}: ${covered.rule}`);
-        const outbound = d.template ? { type: "template", ...d.template } : { type: "message", text: d.text ?? "" };
+        // The same key in every process, so the channel's provider sends it once.
+        const idempotencyKey = d.nudge ? `nudge:${d.nudge}` : d.run ? `run:${d.run}` : `inbox:${this.id}:${d.inbox}`;
+        const outbound = d.template ? { type: "template", ...d.template, idempotencyKey } : { type: "message", text: d.text ?? "", idempotencyKey };
         let failure = null;
         if (this.closed)
             return settle("failed", "this person was forgotten");
@@ -1195,6 +1209,18 @@ export class Conversation {
         this.settings.emit(this.id, "message.out", { text: d.text ?? d.template?.name, channel: d.channel, direct: true });
         settle("sent");
     }
+    async directSettled(d) {
+        const { store } = this.settings;
+        if (d.nudge) {
+            const status = (await store.nudge(d.nudge))?.status;
+            return status !== undefined && !["queued", "held", "scheduled"].includes(status);
+        }
+        if (d.run && d.schedule) {
+            const outcome = (await store.runs(d.schedule)).find((r) => r.id === d.run)?.outcome;
+            return outcome !== undefined && outcome !== "queued" && outcome !== "held";
+        }
+        return false;
+    }
     /**
      * The history the model is sent: all of it while it fits the budget, else the latest entries
      * that do, from the start of one (never between a call and its result), after a line that says

package/dist/src/types.d.ts

@@ -107,6 +107,8 @@ export type Outbound = {
     };
     /** The channel's own params (see Channel.params), as the agent filled them in. */
     fields?: Record<string, unknown>;
+    /** The same in every process for one send the business starts (a nudge, a scheduled text), for providers that take one. */
+    idempotencyKey?: string;
 }
 /** The agent has picked these messages up (WhatsApp's blue ticks). */
  | {
@@ -122,6 +124,7 @@ export type Outbound = {
 /** A template the owner set up with the channel (WhatsApp), sent as is, even outside its window. */
  | ({
     type: "template";
+    idempotencyKey?: string;
 } & Template)
 /** A short line of what the agent is doing, shown in the loading indicator; null clears it. */
  | {

package/flow-messaging/README.md

@@ -148,7 +148,9 @@ Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret
 ## What it does for you
 
 - Every send carries its own Idempotency-Key. A 429 or 5xx is tried again with the same key after
-  a short Retry-After, so a message never goes out twice.
+  a short Retry-After, so a message never goes out twice. A nudge or a scheduled text keeps one key
+  from its id (`nudge:<id>`, `run:<id>`) in every process, so a restart or a second instance does not
+  send it again.
 - Flow's `409 outside_window` becomes the framework's `outside_window`, so the agent knows to send a
   template.
 - A permanent refusal (opted out, no consent, ...) reaches the agent once, with "don't resend it".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {