@flow-engineer/flow 0.0.1 → 0.2.1

package/coding-agents/tools-skill.md

@@ -0,0 +1,89 @@
+---
+name: flow-framework-tools
+description: Write or change a Flow Framework agent's tools and their test files (tests/tools/*.yaml). Load when adding a tool to a Flow Framework agent, changing what a tool returns, or describing how a tool behaves in tests.
+---
+
+# Writing tools for a Flow Framework agent
+
+Read the `flow-framework` skill (`skill.md`) first if you haven't. Tests that use these tool files are
+in the `flow-framework-tests` skill (`test-skill.md`).
+
+## The tool
+
+```ts
+import { tool, z } from "@flow-engineer/flow";
+
+export const findSlots = tool({
+  name: "find_session_slots",
+  description: "Every open time to move the session to, for a date range.",
+  input: z.object({
+    from_date: z.string().optional().describe("First day to search, YYYY-MM-DD; default today"),
+    to_date: z.string().optional().describe("Last day, YYYY-MM-DD; default a week later"),
+  }),
+  run: async ({ from_date, to_date }, { conversationId }) => backend.findSlots(conversationId, from_date, to_date),
+});
+```
+
+- The name and description are what the model reads to choose the tool: say what it does and
+  what it returns, in one line.
+- `input` is a zod schema; Flow Framework checks the model's input against it before `run` is called and
+  sends the model the error if it doesn't fit.
+- `run` returns any JSON-able value; throw to report a failure (the agent sees `Failed: <message>`).
+- Don't make tools for talking to the person (send_<channel>, react, share_updates), for reminders
+  or scheduled messages, or for opting out of messages: Flow Framework has them.
+- Key a person's data by `context.person` (who Flow Framework verified they are) or `context.conversationId`,
+  never by an id the model passed. `context.person` is `key:<resolve's value>`, else
+  `phone:<E.164>` (`phone:+15550100100`), else `<channel>:<address>`. To look the person up in the
+  owner's backend use `context.key`: exactly what `resolve` returned (`customer-7`), or null when
+  they are known only by phone or channel.
+- A tool that changes something (books, pays, sends) passes `context.idempotencyKey` to its backend:
+  it is the same for the same input in the same turn, also when the turn runs again after a
+  restart, so the booking happens once. `context.callId` is the model's id for the call;
+  `context.signal` aborts when the person is forgotten.
+- Don't decide what runs in the background. The reply waits for every call; one moves to the
+  background only if the person writes again meanwhile or it passes its limit (the agent's
+  `deadlineMs`, 60 s by default), and its result comes back into the chat by itself. Set
+  `deadlineMs` on a tool for its own limit: shorter for one that should never hold a reply long,
+  longer for one known to be slow.
+- Say what you covered. An agent reads a list as complete: return the range or filter you
+  searched ("Mon Oct 12 through Sun Oct 18", "all open times") and never cut results short
+  silently. If there are more, say so.
+
+## The tool's test file
+
+In tests no real tool runs: a model plays each tool from the scenario's world. `tests/tools/<tool>.yaml`
+tells it how the tool behaves: every kind of response it gives, each with an example and how long
+it takes. Write one per tool.
+
+```yaml
+tool: place_order
+behaviour: |
+  Order numbers are BL- followed by four digits and go up by one per order. ready_by is about
+  ten minutes after the order is placed. Fails if an item, size or milk is not on the menu.
+responses:
+  - when: The order goes through (usual)
+    latency_ms: 4800
+    input: { name: Sam, items: [{ item: Latte, size: large, milk: oat, quantity: 1 }] }
+    output: { order_id: BL-1040, ready_by: "{{now + 10m}}", pay_at_pickup: true }
+  - when: The point of sale is busy; the order still goes through
+    latency_ms: 11000
+    output: { order_id: BL-1041, ready_by: "{{now + 15m}}", pay_at_pickup: true }
+  - when: The point of sale is down
+    latency_ms: 3000
+    error: Point of sale unavailable
+```
+
+- `behaviour`: what the tool does beyond its description, in plain words (ids, ordering, limits,
+  when it fails).
+- `responses`: one entry per kind of outcome, the usual one first, then slow ones and each error
+  the real system can give. `when` says when it happens; `latency_ms` is how long it takes;
+  then `output` (what `run` returns) or `error` (what it throws). `input` is optional, as an
+  example of a call.
+- Use real responses when you have them (copy them from the agent's recorded tool calls, with
+  personal data removed); otherwise write realistic ones in exactly the shape `run` returns.
+- Examples show the shape, not the answer: the simulator takes ids, names and dates from the
+  scenario's world, the call's input and what the agent already said. Write dates as placeholders
+  for the test's clock (`{{now + 10m}}`, `{{now + 2d | date}}`; see the `flow-framework-tests` skill),
+  never as written dates, which go stale.
+- Latency lives only here. Scenarios describe situations ("the point of sale is slow this
+  morning"); the simulator picks the matching response and latency on each call.

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

@@ -0,0 +1,40 @@
+export declare const API_VERSION = "2026-11-01";
+/** The spec's typed error ({"error": {type, message, channel_code, retry_after, ...}}), or "network". */
+export declare class FlowMessagingError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly channelCode?: string;
+    readonly retryAfter?: number;
+    constructor(status: number, type: string, message: string, extra?: {
+        channelCode?: string;
+        retryAfter?: number;
+    });
+    /** Worth trying again later: rate limits, Flow's or the channel's 5xx, no answer. */
+    get retryable(): boolean;
+}
+/**
+ * One of Flow's object IDs as a URL path segment: `<prefix>_` and letters, digits, `_` or `-` (Flow
+ * makes `<prefix>_<ULID>`). IDs come from inbound events and callers, and every request carries the
+ * key, so anything else (a `/`, `..`, `?`) is refused rather than sent to another path.
+ */
+export declare function idSegment(prefix: string, id: unknown): string;
+export declare class Client {
+    private readonly apiKey;
+    readonly baseUrl: string;
+    constructor(options: {
+        apiKey: string;
+        baseUrl: string;
+    });
+    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>;
+    private request;
+}
+/**
+ * Flow-Signature: `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. Each v1 is HMAC-SHA256, under one of the
+ * endpoint's signing secrets, of `t.<t>.<raw body>`; any match within five minutes of now passes
+ * (two secrets overlap while one is rotated).
+ */
+export declare function verifySignature(body: Buffer, header: string | undefined, secrets: string[], nowSeconds?: number): boolean;

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

@@ -0,0 +1,142 @@
+// A small client for Flow Messaging (api.flow.engineer), against its OpenAPI spec, version
+// 2026-11-01: plain fetch, only the calls the channels and the webhook make.
+//
+// Every POST carries an Idempotency-Key, and a retry repeats the same key, so a send is never made
+// twice. A 429 or a 5xx is tried again in place after its Retry-After when that is short; a longer
+// wait, or any other error, is raised as FlowMessagingError (the spec's typed error). Keys and
+// message text are never logged.
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+export const API_VERSION = "2026-11-01";
+const TRIES = 3;
+/** The longest Retry-After waited out in place (seconds); a longer one is the caller's. */
+const MAX_WAIT = 10;
+const TIMEOUT_MS = 20_000;
+/** How far a webhook's signed timestamp may be from now (seconds), as the spec says. */
+const SIGNATURE_TOLERANCE = 300;
+/** The spec's typed error ({"error": {type, message, channel_code, retry_after, ...}}), or "network". */
+export class FlowMessagingError extends Error {
+    status;
+    type;
+    channelCode;
+    retryAfter;
+    constructor(status, type, message, extra = {}) {
+        super(message);
+        this.name = "FlowMessagingError";
+        this.status = status;
+        this.type = type;
+        this.channelCode = extra.channelCode;
+        this.retryAfter = extra.retryAfter;
+    }
+    /** Worth trying again later: rate limits, Flow's or the channel's 5xx, no answer. */
+    get retryable() {
+        return this.status === 0 || this.status === 429 || this.status >= 500 || (this.type === "idempotency_conflict" && this.channelCode === "in_progress");
+    }
+}
+/**
+ * One of Flow's object IDs as a URL path segment: `<prefix>_` and letters, digits, `_` or `-` (Flow
+ * makes `<prefix>_<ULID>`). IDs come from inbound events and callers, and every request carries the
+ * key, so anything else (a `/`, `..`, `?`) is refused rather than sent to another path.
+ */
+export function idSegment(prefix, id) {
+    if (typeof id !== "string" || !new RegExp(`^${prefix}_[A-Za-z0-9_-]+$`).test(id)) {
+        throw new Error(`not a Flow Messaging ${prefix}_ id: ${JSON.stringify(String(id)).slice(0, 80)}`);
+    }
+    return encodeURIComponent(id);
+}
+export class Client {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        let end = options.baseUrl.length;
+        while (end > 0 && options.baseUrl[end - 1] === "/")
+            end--;
+        this.baseUrl = options.baseUrl.slice(0, end);
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
+    async download(fileId) {
+        const path = `/v1/files/${idSegment("file", fileId)}`;
+        if (!this.apiKey)
+            throw new Error("set FLOW_MESSAGING_KEY (or pass apiKey) to reach Flow Messaging");
+        const response = await fetch(this.baseUrl + path, { headers: { authorization: `Bearer ${this.apiKey}`, "flow-version": API_VERSION }, signal: AbortSignal.timeout(60_000) });
+        if (!response.ok)
+            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);
+    }
+    async request(method, path, body, idempotencyKey, tries = TRIES) {
+        if (!this.apiKey)
+            throw new Error("set FLOW_MESSAGING_KEY (or pass apiKey) to reach Flow Messaging");
+        const headers = { authorization: `Bearer ${this.apiKey}`, "flow-version": API_VERSION };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        if (idempotencyKey)
+            headers["idempotency-key"] = idempotencyKey;
+        let last;
+        for (let attempt = 1; attempt <= tries; attempt++) {
+            let response;
+            try {
+                response = await fetch(this.baseUrl + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(TIMEOUT_MS) });
+            }
+            catch (error) {
+                last = new FlowMessagingError(0, "network", `no answer from Flow Messaging (${error instanceof Error ? error.name : "error"})`);
+                if (attempt < tries)
+                    await wait(2 ** (attempt - 1));
+                continue;
+            }
+            if (response.ok) {
+                const text = await response.text();
+                return (text ? JSON.parse(text) : {});
+            }
+            last = await errorOf(response);
+            const pause = last.retryAfter ?? 2 ** (attempt - 1);
+            if (!last.retryable || attempt === tries || pause > MAX_WAIT)
+                throw last;
+            await wait(pause);
+        }
+        throw last;
+    }
+}
+async function errorOf(response) {
+    let body = {};
+    try {
+        const parsed = (await response.json());
+        if (parsed && typeof parsed.error === "object")
+            body = parsed.error;
+    }
+    catch { }
+    const header = Number(response.headers.get("retry-after"));
+    const retryAfter = typeof body.retry_after === "number" ? body.retry_after : Number.isFinite(header) && response.headers.has("retry-after") ? header : undefined;
+    const type = body.type ?? (response.status >= 500 ? "api_error" : "invalid_request");
+    return new FlowMessagingError(response.status, type, body.message ?? `Flow Messaging answered ${response.status}`, { channelCode: body.channel_code, retryAfter });
+}
+const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+/**
+ * Flow-Signature: `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. Each v1 is HMAC-SHA256, under one of the
+ * endpoint's signing secrets, of `t.<t>.<raw body>`; any match within five minutes of now passes
+ * (two secrets overlap while one is rotated).
+ */
+export function verifySignature(body, header, secrets, nowSeconds = Date.now() / 1000) {
+    let stamp = "";
+    const given = [];
+    for (const part of (header ?? "").split(",")) {
+        const [key, value = ""] = part.trim().split("=", 2);
+        if (key === "t")
+            stamp = value;
+        else if (key === "v1" && value)
+            given.push(value);
+    }
+    if (!/^\d+$/.test(stamp) || !given.length || Math.abs(nowSeconds - Number(stamp)) > SIGNATURE_TOLERANCE)
+        return false;
+    const signed = Buffer.concat([Buffer.from(`t.${stamp}.`), body]);
+    return secrets.some((secret) => {
+        const expected = Buffer.from(createHmac("sha256", secret).update(signed).digest("hex"));
+        return given.some((value) => value.length === expected.length && timingSafeEqual(Buffer.from(value), expected));
+    });
+}

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

@@ -0,0 +1,72 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type Agent, type Channel, type ChannelInfo, type WhatsAppFeature } from "../../src/index.ts";
+export { API_VERSION, FlowMessagingError, verifySignature } from "./client.ts";
+export interface FlowMessagingOptions {
+    /** The app's API key, `fk_live_...` or `fk_test_...`. Default: FLOW_MESSAGING_KEY (or the older FLOW_MESSAGING_API_KEY). */
+    apiKey?: string;
+    /** The webhook endpoint's signing secret(s), comma-separated while one is rotated. Default: FLOW_MESSAGING_WEBHOOK_SECRET. */
+    webhookSecret?: string;
+    /** Default: FLOW_MESSAGING_BASE_URL (or the older FLOW_MESSAGING_API_URL), else https://api.flow.engineer. */
+    baseUrl?: string;
+}
+export interface FlowChannelOptions {
+    /** The Flow sender (`snd_...`) this channel starts conversations from. Default: FLOW_MESSAGING_<CHANNEL>_SENDER. */
+    sender?: string;
+    /** The agent's name for the channel. Default: whatsapp, telegram, imessage or sms. */
+    name?: string;
+    instructions?: string;
+}
+/** What the webhook and the stream need of an agent. */
+export type WebhookAgent = Pick<Agent, "message" | "reacted" | "undelivered">;
+export interface StreamOptions {
+    /**
+     * A file that keeps the ID of the last event the agent handled, so a restart resumes after it and
+     * Flow replays what arrived while the agent was away (for as long as the plan keeps events, 30 days
+     * by default). Without it the cursor is in memory: a dropped stream still resumes, a restart starts from now.
+     */
+    cursorFile?: string;
+}
+/** Why the stream stopped for good: Flow refused the key or the request, so reconnecting cannot help. */
+export interface StreamStop {
+    /** The WebSocket close code, such as 4401 (authentication) or 4403 (permission). */
+    code: number;
+    type: string;
+    message: string;
+}
+export interface StreamHandle {
+    /** Closes the stream and waits for the event being handled. */
+    close(): Promise<void>;
+    /** Resolves when Flow refused the stream for good (a bad or revoked key, say); never after close(). */
+    stopped: Promise<StreamStop>;
+}
+/** Telegram as Flow sends it: an inline keyboard of up to 10 buttons (or one link), photos, Markdown, no read receipts for bots. */
+export declare const TELEGRAM: ChannelInfo;
+/**
+ * iMessage as Flow sends it: plain text up to 9999 characters, photos, inline replies, tapbacks
+ * (other emoji go as emoji reactions), typing and read receipts (the whole conversation). No buttons,
+ * lists or templates. No reply window is set: the line only answers people who wrote to it, and a
+ * send it will not deliver comes back as Not delivered (outside_window).
+ */
+export declare const IMESSAGE: ChannelInfo;
+export declare function flowMessaging(options?: FlowMessagingOptions): {
+    whatsapp: (o?: FlowChannelOptions & {
+        disable?: WhatsAppFeature[];
+    }) => Channel;
+    telegram: (o?: FlowChannelOptions) => Channel;
+    imessage: (o?: FlowChannelOptions) => Channel;
+    sms: (o?: FlowChannelOptions) => Channel;
+    webhook: (agent: WebhookAgent) => (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    receive: (agent: WebhookAgent, request: {
+        body: Buffer | string;
+        headers: Record<string, string | string[] | undefined>;
+    }) => Promise<{
+        status: number;
+        body: string;
+    }>;
+    stream: (agent: WebhookAgent, o?: StreamOptions) => StreamHandle;
+    start: (agent: WebhookAgent, o?: StreamOptions & {
+        port?: number;
+    }) => StreamHandle & {
+        mode: "webhook" | "stream";
+    };
+};