@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/src/traces.js

@@ -0,0 +1,303 @@
+// Traces of every turn, for a traces endpoint (a dashboard that shows and grades conversations).
+// An event sink like any other: it folds a conversation's events into one trace per turn (a root
+// span, a span per model call, per tool and per message sent) and posts them as OTLP/JSON to
+// `<url>/v1/traces` with the agent's trace key.
+//
+// It never slows or breaks a conversation: a finished turn is queued (bounded; the oldest goes when
+// it is full) and sent in the background, every turn finished meanwhile in the same request; a
+// failed request is dropped, logged once per kind of failure, and never names the key.
+//
+// Content (what the person and the agent wrote, tool inputs and results) is sent only with
+// `content: true` (FLOW_FRAMEWORK_TRACES_CONTENT=1); without it the spans hold ids, names, timing and counts,
+// and the endpoint has no messages to show or grade.
+//
+// Under `flow test`, which plays the agent in this process, every trace says so: the CLI sets
+// FLOW_FRAMEWORK_RUN_KIND=test before it loads the agent, and FLOW_FRAMEWORK_TEST_SESSION once the session opens.
+// The resource's `chinwag.run_kind` is then "test" (else "production") and each turn's root span
+// names the session (`chinwag.test.session`), so the endpoint keeps test traces apart from real
+// conversations and links them to their test run.
+import { randomBytes } from "node:crypto";
+import { setting } from "./names.js";
+/** Finished turns waiting to be sent; past this the oldest is dropped. */
+const MAX_QUEUED = 512;
+/** Turns per request. */
+const BATCH = 64;
+const TIMEOUT_MS = 10_000;
+/** The cap per content attribute. */
+const MAX_TEXT = 32 * 1024;
+/** Where traces go when a key is set and no address is, and the test cloud `flow test` uses when none is named. */
+export const OBSERVE_URL = "https://flow.engineer/observe";
+/** A setting from the environment: FLOW_FRAMEWORK_<name>, else CHINWAG_<name> (src/names.ts). */
+export { setting };
+/**
+ * The traces options from the environment: on when FLOW_FRAMEWORK_TRACES_KEY is set, except under
+ * `node --test` (NODE_TEST_CONTEXT), so an agent's own tests never send their turns. The address
+ * is FLOW_FRAMEWORK_TRACES_URL, else {@link OBSERVE_URL}.
+ */
+export function tracesFromEnv(env = process.env) {
+    const key = setting("TRACES_KEY", env)?.trim() ?? "";
+    if (!key || env.NODE_TEST_CONTEXT)
+        return undefined;
+    return { key, url: setting("TRACES_URL", env)?.trim() || OBSERVE_URL, content: setting("TRACES_CONTENT", env) === "1" };
+}
+/** The endpoint's channel names: Flow Framework's custom UIs are web or app chats. */
+const CHANNEL_KIND = { sms: "sms", whatsapp: "whatsapp", custom: "web" };
+let warnedMetadataOnly = false;
+export function traces(options, agent) {
+    const base = (options.url ?? "").replace(/\/+$/, "");
+    if (!options.key)
+        throw new Error("flow: traces need a key");
+    if (!base)
+        throw new Error("flow: traces need your traces endpoint's URL");
+    if (!allowedUrl(base))
+        throw new Error("flow: traces go over https (http only to this machine)");
+    const endpoint = `${base}/v1/traces`;
+    const content = options.content === true;
+    if (!content && !warnedMetadataOnly) {
+        warnedMetadataOnly = true;
+        console.warn("flow: traces are metadata only. Set FLOW_FRAMEWORK_TRACES_CONTENT=1 to send what was written.");
+    }
+    const open = new Map();
+    /** Messages and background results that came while no turn was open: they join the next one. */
+    const waiting = new Map();
+    const queue = [];
+    const warned = new Set();
+    let sending = null;
+    const testRun = setting("RUN_KIND") === "test";
+    const resource = [attr("service.name", agent.service), attr("telemetry.sdk.name", "chinwag"), attr("chinwag.run_kind", testRun ? "test" : "production")];
+    if (options.version)
+        resource.push(attr("service.version", options.version));
+    function warnOnce(kind, message) {
+        if (warned.has(kind))
+            return;
+        warned.add(kind);
+        console.warn(`flow: ${message}; later failures of this kind are not logged`);
+    }
+    const kindOf = (channel) => (channel ? CHANNEL_KIND[agent.kindOf(channel) ?? ""] ?? "other" : undefined);
+    function waitingFor(id) {
+        let w = waiting.get(id);
+        if (!w)
+            waiting.set(id, (w = { inbound: [], spans: [] }));
+        return w;
+    }
+    function child(turn, name, start, end, attributes, failed = false) {
+        return span(turn.traceId, name, start, end, attributes, turn.rootId, failed);
+    }
+    function begin(conversationId, at) {
+        finish(conversationId, false, at);
+        const w = waiting.get(conversationId);
+        waiting.delete(conversationId);
+        const inbound = w?.inbound ?? [];
+        const turn = { traceId: hex(16), rootId: hex(8), start: Math.min(at, ...inbound.map((m) => m.at)), inbound, spans: [], tools: new Map() };
+        for (const make of w?.spans ?? [])
+            turn.spans.push(make(turn));
+        open.set(conversationId, turn);
+    }
+    function finish(conversationId, failed, at) {
+        const turn = open.get(conversationId);
+        if (!turn)
+            return;
+        open.delete(conversationId);
+        record(conversationId, turn, failed, at);
+    }
+    function record(conversationId, turn, failed, at) {
+        const attributes = [attr("gen_ai.operation.name", "invoke_agent"), attr("gen_ai.agent.name", agent.service), ...ids(conversationId)];
+        const channel = kindOf(turn.inbound.at(-1)?.channel ?? turn.replyChannel);
+        if (channel)
+            attributes.push(attr("chinwag.channel", channel));
+        const session = testRun ? setting("TEST_SESSION") : undefined;
+        if (session)
+            attributes.push(attr("chinwag.test.session", session));
+        if (turn.inbound.length) {
+            attributes.push(attr("chinwag.messages", turn.inbound.length));
+            if (turn.inbound[0].messageId)
+                attributes.push(attr("chinwag.message_id", turn.inbound[0].messageId));
+            if (content)
+                attributes.push(attr("chinwag.user_message", clip(turn.inbound.map((m) => m.text).join("\n"))));
+        }
+        const root = { ...span(turn.traceId, `invoke_agent ${agent.service}`, turn.start, at, attributes, undefined, failed), spanId: turn.rootId };
+        enqueue([root, ...turn.spans]);
+    }
+    /** A message sent outside any turn (one the business wrote, or a rule's answer, sent as is): a trace of its own. */
+    function alone(conversationId, at, channel, text) {
+        const turn = { traceId: hex(16), rootId: hex(8), start: at, inbound: [], spans: [], tools: new Map(), replyChannel: channel };
+        turn.spans.push(reply(turn, at, channel, text));
+        record(conversationId, turn, false, at);
+    }
+    function reply(turn, at, channel, text) {
+        turn.replyChannel ??= channel;
+        const attributes = [attr("chinwag.channel", channel)];
+        if (content && typeof text === "string")
+            attributes.push(attr("chinwag.agent_reply", clip(text)));
+        return child(turn, `send ${channel}`, at, at, attributes);
+    }
+    function enqueue(spans) {
+        queue.push(spans);
+        if (queue.length > MAX_QUEUED) {
+            queue.shift();
+            warnOnce("queue", "traces could not be sent fast enough and the oldest turns were dropped");
+        }
+        void drain();
+    }
+    function drain() {
+        sending ??= (async () => {
+            while (queue.length)
+                await post(queue.splice(0, BATCH).flat());
+        })().finally(() => (sending = null));
+        return sending;
+    }
+    async function post(spans) {
+        const body = JSON.stringify({ resourceSpans: [{ resource: { attributes: resource }, scopeSpans: [{ scope: { name: "chinwag" }, spans }] }] });
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${options.key}` },
+                body,
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            const answer = await response.text();
+            if (!response.ok)
+                return warnOnce(`http ${response.status}`, `the traces endpoint refused traces (HTTP ${response.status})`);
+            const rejected = Number(parseJson(answer)?.partialSuccess?.rejectedSpans ?? 0);
+            if (rejected > 0)
+                warnOnce("partial", `the traces endpoint rejected ${rejected} span(s) of a trace`);
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : "error";
+            warnOnce(`network ${name}`, `traces could not reach the traces endpoint (${name})`);
+        }
+    }
+    function handle(e) {
+        const id = e.conversationId;
+        const turn = open.get(id);
+        switch (e.type) {
+            case "message.arrived":
+            case "turn.context":
+                return;
+            case "message.in": {
+                // A voice note's text is its transcript (and any caption).
+                const text = [e.transcript, e.text].filter(Boolean).join(" ");
+                const m = { at: e.at, text, channel: String(e.channel ?? ""), messageId: e.ownId ? String(e.messageId) : undefined };
+                // Answered with no model call (intercept, a keyword): a trace of its own, never part of a turn.
+                if (e.answered)
+                    return record(id, { traceId: hex(16), rootId: hex(8), start: e.at, inbound: [m], spans: [], tools: new Map() }, false, e.at);
+                (turn ?? waitingFor(id)).inbound.push(m);
+                return;
+            }
+            case "turn.start":
+                return begin(id, e.at);
+            case "turn.end":
+                return finish(id, false, e.at);
+            case "model.error":
+                return finish(id, true, e.at);
+            case "message.out":
+                if (!turn || e.answered)
+                    return alone(id, e.at, String(e.channel), e.text);
+                turn.spans.push(reply(turn, e.at, String(e.channel), e.text));
+                return;
+            case "model.call": {
+                if (!turn)
+                    return;
+                const ms = Number(e.ms ?? 0);
+                const usage = e.usage;
+                const model = typeof e.model === "string" ? e.model : undefined;
+                const attributes = [attr("gen_ai.operation.name", "chat")];
+                if (model)
+                    attributes.push(attr("gen_ai.response.model", model));
+                if (usage?.inputTokens !== undefined)
+                    attributes.push(attr("gen_ai.usage.input_tokens", usage.inputTokens));
+                if (usage?.outputTokens !== undefined)
+                    attributes.push(attr("gen_ai.usage.output_tokens", usage.outputTokens));
+                turn.spans.push(child(turn, model ? `chat ${model}` : "chat", e.at - ms, e.at, attributes));
+                return;
+            }
+            case "tool.start":
+                turn?.tools.set(String(e.callId), { at: e.at, input: e.input });
+                return;
+            case "tool.end":
+            case "tool.detached": {
+                if (!turn)
+                    return;
+                const started = turn.tools.get(String(e.callId));
+                turn.tools.delete(String(e.callId));
+                const attributes = toolAttributes(e, started?.input);
+                if (e.type === "tool.detached")
+                    attributes.push(attr("chinwag.tool.background", true));
+                turn.spans.push(child(turn, `execute_tool ${e.tool}`, started?.at ?? e.at - Number(e.ms ?? 0), e.at, attributes, e.ok === false));
+                return;
+            }
+            case "task.done": {
+                // A background tool finished: its result starts the next turn, which this span joins.
+                const make = (t) => child(t, `execute_tool ${e.tool}`, e.at - Number(e.ms ?? 0), e.at, [...toolAttributes(e), attr("chinwag.tool.background", true)], e.ok === false);
+                if (turn)
+                    turn.spans.push(make(turn));
+                else
+                    waitingFor(id).spans.push(make);
+                return;
+            }
+        }
+    }
+    function toolAttributes(e, input) {
+        const attributes = [attr("gen_ai.operation.name", "execute_tool"), attr("gen_ai.tool.name", String(e.tool)), attr("gen_ai.tool.call.id", String(e.callId))];
+        if (content && input !== undefined)
+            attributes.push(attr("gen_ai.tool.call.arguments", clip(JSON.stringify(input))));
+        if (content && typeof e.output === "string")
+            attributes.push(attr("gen_ai.tool.call.result", clip(e.output)));
+        return attributes;
+    }
+    return {
+        sink: (event) => {
+            try {
+                handle(event);
+            }
+            catch (error) {
+                warnOnce("sink", `traces skipped an event (${error instanceof Error ? error.name : "error"})`);
+            }
+        },
+        flush: () => drain(),
+    };
+}
+/** The endpoint's ids: the conversation is the person (Flow Framework keeps one per person across channels). */
+function ids(conversationId) {
+    return [attr("chinwag.conversation_id", conversationId), attr("chinwag.contact_id", conversationId)];
+}
+function span(traceId, name, start, end, attributes, parentSpanId, failed = false) {
+    return {
+        traceId,
+        spanId: hex(8),
+        ...(parentSpanId ? { parentSpanId } : {}),
+        name,
+        kind: 1,
+        startTimeUnixNano: nanos(start),
+        endTimeUnixNano: nanos(Math.max(start, end)),
+        attributes,
+        ...(failed ? { status: { code: 2 } } : {}),
+    };
+}
+function attr(key, value) {
+    if (typeof value === "boolean")
+        return { key, value: { boolValue: value } };
+    if (typeof value === "number")
+        return { key, value: Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value } };
+    return { key, value: { stringValue: value } };
+}
+const hex = (bytes) => randomBytes(bytes).toString("hex");
+const nanos = (ms) => (BigInt(Math.round(ms)) * 1000000n).toString();
+const clip = (text) => (text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}… [truncated]` : text);
+function allowedUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === "https:" || (u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,260 @@
+export interface ToolCall {
+    id: string;
+    name: string;
+    /** The model's arguments as it wrote them (a JSON string). */
+    arguments: string;
+}
+export type ChatMessage = {
+    role: "user";
+    content: string;
+    media?: Media[];
+    messages?: PersonMessage[];
+} | {
+    role: "assistant";
+    content: string | null;
+    toolCalls?: ToolCall[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+};
+/**
+ * One of the person's messages in a history entry, kept beside its text (never sent to the model):
+ * its id (the provider's, or Flow Framework's m1, m2, ...), its channel, and what they wrote or tapped.
+ */
+export interface PersonMessage {
+    id: string;
+    channel: string;
+    text: string;
+    /** They tapped a button or list row. */
+    choice?: boolean;
+}
+/**
+ * A photo or PDF in the person's messages, for the model to read. `data` (base64) is held in memory
+ * only while the model is shown it, never stored; without it, the model is told it is no longer shown.
+ */
+export interface Media {
+    kind: "image" | "document";
+    mime: string;
+    name?: string;
+    data?: string;
+}
+export interface ToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema of the tool's input. */
+    parameters: Record<string, unknown>;
+}
+export interface ModelRequest {
+    system: string;
+    messages: ChatMessage[];
+    tools: ToolSpec[];
+    /** Aborted when the step is no longer wanted (the person sent another message). */
+    signal: AbortSignal;
+}
+export interface ModelResponse {
+    /** Text outside any tool call. Never shown to the person; kept in history as the agent's note. */
+    text: string | null;
+    toolCalls: ToolCall[];
+    /** costUsd when the provider reports it (OpenRouter does). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd?: number;
+    };
+    /** The model that answered, as the provider names it. */
+    model?: string;
+}
+/** Any model behind Flow Framework. `complete` must reject promptly when `signal` aborts. */
+export interface Model {
+    complete(request: ModelRequest): Promise<ModelResponse>;
+    /** Its context window in tokens, when known: each call is kept well within it (see `history`). */
+    contextTokens?: number;
+    /** What it reads besides text, as `media` on the person's messages. Without it: text only, and a note for each photo or PDF. */
+    reads?: {
+        images?: boolean;
+        pdfs?: boolean;
+    };
+}
+export interface ListRow {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** What a conversation sends to its channel. */
+export type Outbound = {
+    type: "message";
+    text: string;
+    /** The person's message this one quotes (channels with replies). */
+    replyTo?: string;
+    /** Reply buttons; a tap comes back as the person's message. */
+    buttons?: string[];
+    /** A list the person picks one row from. */
+    list?: {
+        button: string;
+        rows: ListRow[];
+    };
+    /** A button that opens this https page; only on channels with linkButton (elsewhere Flow Framework puts the URL in the text). */
+    link?: {
+        label: string;
+        url: string;
+    };
+    /** A photo by https URL, the text its caption; only on channels with images (elsewhere the text goes alone). */
+    image?: {
+        url: string;
+    };
+    /** The channel's own params (see Channel.params), as the agent filled them in. */
+    fields?: Record<string, unknown>;
+}
+/** The agent has picked these messages up (WhatsApp's blue ticks). */
+ | {
+    type: "read";
+    messageIds: string[];
+}
+/** A reaction on one of the person's messages, by the id Flow Framework gave it. */
+ | {
+    type: "reaction";
+    emoji: string;
+    messageId: string;
+}
+/** A template the owner set up with the channel (WhatsApp), sent as is, even outside its window. */
+ | ({
+    type: "template";
+} & Template)
+/** A short line of what the agent is doing, shown in the loading indicator; null clears it. */
+ | {
+    type: "status";
+    text: string | null;
+} | {
+    type: "typing";
+    on: boolean;
+};
+/** A WhatsApp template as it is sent: its name and the values for its placeholders (Meta's template parameters). */
+export interface Template {
+    /** Its name as approved (or the provider's own id for it). */
+    name: string;
+    language?: string;
+    /** The header's value: the text for its {{1}}, or its photo, video or document by https URL or the provider's file id. */
+    header?: {
+        kind: "text";
+        text: string;
+    } | {
+        kind: "image" | "video" | "document";
+        url?: string;
+        fileId?: string;
+    };
+    /** Values for the body's {{1}}, {{2}}, ... in order. */
+    body?: string[];
+    /** Values for the buttons that take one, by the button's position from 0: a URL button's suffix, a quick reply's payload. */
+    buttons?: Array<{
+        index: number;
+        value: string;
+    }>;
+    /** The body's values by number ({ "1": "Maria" }), the older form of `body`: give one or the other. */
+    variables?: Record<string, string>;
+}
+/**
+ * A WhatsApp template as the owner set it up with Meta, declared in `createAgent({ templates })`:
+ * Flow Framework checks every send of it against this, and the playground shows it as WhatsApp would.
+ */
+export interface TemplateDefinition {
+    name: string;
+    /** Meta's language code: en, en_US, hi. */
+    language: string;
+    category: "utility" | "marketing" | "authentication";
+    /** Text (which may hold one {{1}}), or a photo, video or document sent with each message. */
+    header?: {
+        kind: "text";
+        text: string;
+    } | {
+        kind: "image" | "video" | "document";
+    };
+    /** The message, with {{1}}, {{2}}, ... where its values go. */
+    body: string;
+    footer?: string;
+    /** Quick replies come back as the person's tap; a URL may end in {{1}}, its value given at each send. */
+    buttons?: TemplateButton[];
+}
+export type TemplateButton = {
+    type: "quick_reply";
+    text: string;
+} | {
+    type: "url";
+    text: string;
+    url: string;
+} | {
+    type: "phone";
+    text: string;
+    phone: string;
+};
+/** Sends one outbound; a rejection means it did not reach the person. */
+export type Deliver = (outbound: Outbound) => Promise<void> | void;
+/** What the channel a conversation is on can show. */
+export interface ChannelInfo {
+    /** Reactions on the person's message (WhatsApp, iMessage, web); plain SMS has none. */
+    reactions: boolean;
+    /** A live status line in the loading indicator (web and app UIs). */
+    status: boolean;
+    /** How text is formatted: none (SMS shows markdown raw), WhatsApp's own marks, or Markdown. */
+    formatting?: "plain" | "whatsapp" | "markdown";
+    /** The most characters one message can carry. */
+    maxLength?: number;
+    /** A message can quote one of the person's messages. */
+    replies?: boolean;
+    /** Reply buttons under a message. */
+    buttons?: {
+        max: number;
+        labelMax: number;
+    };
+    /** A list the person picks one row from. */
+    lists?: {
+        maxRows: number;
+        titleMax: number;
+        buttonMax: number;
+    };
+    /** One button under a message that opens a web page (WhatsApp's call-to-action URL button). */
+    linkButton?: {
+        labelMax: number;
+    };
+    /** Photos sent by URL, with the message's text as their caption. */
+    images?: {
+        captionMax: number;
+    };
+    /** The channel shows the person when their message has been read. */
+    readReceipts?: boolean;
+    /**
+     * The business may message first only this many hours after the person's last message
+     * (WhatsApp: 24); after that, only templates.
+     */
+    replyWindowHours?: number;
+}
+/** A message from the person, with what the channel knows about it. */
+export interface Incoming {
+    text: string;
+    /** The message they replied to (theirs or the agent's), quoted. */
+    replyTo?: {
+        text: string;
+        fromAgent: boolean;
+    };
+    /** They tapped a button or picked a list row rather than typing. */
+    choice?: {
+        id?: string;
+        title: string;
+    };
+    /** Photos, voice notes and documents sent with it; `text` is then their caption, or "". */
+    attachments?: Attachment[];
+}
+/** A file the person sent. Its bytes are fetched only when the agent can use them. */
+export interface Attachment {
+    kind: "image" | "audio" | "document";
+    mime: string;
+    /** The file name, when the channel gives one (documents). */
+    name?: string;
+    /** The bytes. A provider fetches its media here with its own credentials: no URL reaches the model. */
+    data(): Promise<Uint8Array>;
+}
+/** Turns a voice note into text, with whatever speech-to-text the agent's author chose. */
+export type Transcribe = (audio: {
+    mime: string;
+    data: Uint8Array;
+}) => Promise<string>;

package/dist/src/types.js

@@ -0,0 +1,2 @@
+// The shapes every part of Flow Framework shares: chat history, the model contract, what a channel is sent.
+export {};

package/dist/testing/src/account.d.ts

@@ -0,0 +1,4 @@
+export declare const ACCOUNT_COMMANDS: Set<string>;
+export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--ci] [--json]\n                            Write this agent's keys (test cloud, traces, Flow Messaging) and each\n                            open channel's sender into ./.env (in an agent's folder: package.json)\n  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet";
+/** Runs one account command; resolves to the exit status. */
+export declare function accountCli(command: string, args: string[]): Promise<number>;