@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/testing/src/chat.js

@@ -0,0 +1,117 @@
+// `flow chat`: talk to the agent in this folder from the terminal, with no account and no channel.
+// It builds the agent from src/agent.ts (buildAgent({ events }), as `flow test` does) with the
+// model key in .env, and writes as the agent's first test person, the way the playground does
+// (agent.simulate). Each line read from stdin is one message; the agent's replies are printed once
+// its turn is over, so it works typed by a person or piped by a coding agent:
+//   printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat
+// --json prints each thing the agent sends as one JSON line. The conversation lives only as long as
+// the command. Exit status: 0 done (stdin ended), 1 usage or the agent could not be built.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { loadEnv } from "./report.js";
+export const CHAT_LINE = `  flow chat [--channel <name>] [--person <phone>] [--json]
+                            Talk to the agent in this folder from the terminal: one message per line
+                            of stdin, no account needed (only the model key in .env)`;
+const USAGE = `Usage:\n${CHAT_LINE}
+
+Writes as the agent's first test person (createAgent({ testPeople })) on its first channel, unless
+--person or --channel says otherwise. Exit status: 0 done, 1 usage or the agent could not be built.`;
+/** Runs `flow chat`; resolves to the exit status. */
+export async function chatCli(args, input = process.stdin) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args, strict: true, options: { channel: { type: "string" }, person: { type: "string" }, json: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } } }));
+    }
+    catch (error) {
+        console.error(`flow chat: ${error.message.split(". ")[0]}\n\n${USAGE}`);
+        return 1;
+    }
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    loadEnv(undefined);
+    const file = join(process.cwd(), "src", "agent.ts");
+    if (!existsSync(file)) {
+        console.error(`flow chat: no src/agent.ts here. Run it from your agent's folder (npx @flow-engineer/flow init makes one).`);
+        return 1;
+    }
+    const turns = [];
+    let agent;
+    try {
+        const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        if (typeof module.buildAgent !== "function")
+            throw new Error("src/agent.ts must export buildAgent({ events }).");
+        agent = module.buildAgent({ events: [(event) => turns.forEach((listener) => listener(event))] });
+    }
+    catch (error) {
+        console.error(`flow chat: ${error.message}`);
+        return 1;
+    }
+    const person = values.person ? agent.testPeople().find((p) => p.phone.replace(/\D/g, "") === values.person.replace(/\D/g, "")) : agent.testPeople()[0];
+    const channel = values.channel ? agent.channels().find((c) => c.name === values.channel) : agent.channels()[0];
+    if (!person || !channel) {
+        console.error(!person
+            ? `flow chat: ${values.person ? `${values.person} is not one of the agent's testPeople` : "the agent has no testPeople"}; declare them in createAgent({ testPeople: [{ name, phone }] }).`
+            : `flow chat: ${values.channel ? `no channel named ${values.channel}` : "the agent has no channels"}; it has ${agent.channels().map((c) => c.name).join(", ") || "none"}.`);
+        return 1;
+    }
+    agent.attachPlayground(({ outbound }) => print(outbound, channel.name, values.json === true));
+    turns.push((event) => {
+        if (event.type === "model.error")
+            console.error(`flow chat: the model failed: ${String(event.error ?? event.message ?? "error")}`);
+    });
+    const prompt = process.stdin.isTTY && input === process.stdin;
+    if (!values.json)
+        console.error(`Talking to the agent on ${channel.name} as ${person.name} (${person.phone}). Ctrl-D ends.`);
+    const lines = createInterface({ input, terminal: false });
+    if (prompt)
+        process.stderr.write("you: ");
+    let conversationId;
+    for await (const line of lines) {
+        const text = line.trim();
+        if (text) {
+            const taken = await agent.simulate({ person: person.phone, channel: channel.name, message: text });
+            if (taken)
+                await agent.conversation((conversationId = taken.conversationId))?.whenIdle();
+        }
+        if (prompt)
+            process.stderr.write("you: ");
+    }
+    // A tool still running in the background answers in a turn of its own: wait for it before leaving.
+    while (conversationId && agent.status().backgroundTasks > 0) {
+        await new Promise((done) => turns.push((event) => event.type === "task.done" && done()));
+        await agent.conversation(conversationId)?.whenIdle();
+    }
+    await agent.flushTraces();
+    return 0;
+}
+/** One thing the agent sent, as a person would read it (or one JSON line). */
+function print(outbound, channel, json) {
+    if (outbound.type === "typing" || outbound.type === "status" || outbound.type === "read")
+        return;
+    if (json)
+        return void process.stdout.write(`${JSON.stringify({ channel, ...outbound })}\n`);
+    if (outbound.type === "reaction")
+        return void process.stdout.write(`agent reacted ${outbound.emoji}\n`);
+    if (outbound.type === "template")
+        return void process.stdout.write(`agent: [template ${outbound.name}]\n`);
+    const extra = [
+        outbound.image && `[photo ${outbound.image.url}]`,
+        outbound.link && `[${outbound.link.label}: ${outbound.link.url}]`,
+        outbound.buttons?.map((b) => `[${b}]`).join(" "),
+        outbound.list && `[${outbound.list.button}: ${outbound.list.rows.map((r) => r.title).join(" | ")}]`,
+    ].filter(Boolean);
+    process.stdout.write(`agent: ${[outbound.text, ...extra].filter(Boolean).join(" ")}\n`);
+}

package/dist/testing/src/check-endpoint.d.ts

@@ -0,0 +1,31 @@
+import { type HttpAgentRequest } from "./http-agent.ts";
+/** One synthetic conversation: its messages go one at a time, each once the last one's answer is in. */
+interface Case {
+    id: string;
+    title: string;
+    messages: Array<{
+        messageId: string;
+        message: HttpAgentRequest["message"];
+    }>;
+}
+export declare const CASES: Case[];
+export interface CaseResult {
+    id: string;
+    title: string;
+    pass: boolean;
+    /** What went wrong, or what came back. */
+    detail: string;
+    /** Each message's replies, as the endpoint answered them. */
+    answers: Array<{
+        messageId: string;
+        replies: unknown[];
+    }>;
+}
+export declare function checkEndpoint(options: {
+    url: string;
+    token?: string;
+    timeoutMs?: number;
+}): Promise<CaseResult[]>;
+/** The command: prints one line per case (or JSON) and returns the exit status. */
+export declare function checkEndpointCli(args: string[], env?: Record<string, string | undefined>, print?: (...data: any[]) => void, printError?: (...data: any[]) => void): Promise<number>;
+export {};

package/dist/testing/src/check-endpoint.js

@@ -0,0 +1,158 @@
+// `flow check-endpoint <url>`: checks an agent's HTTP endpoint against the contract in spec/
+// (agent-endpoint.openapi.yaml, request.schema.json, response.schema.json) before any test run. It
+// POSTs a fixed set of synthetic messages, as `flow test --agent-url` would, and checks each
+// answer: the status and body (the same rules a run applies, testing/src/http-agent.ts), the
+// response schema, what WhatsApp can show, and that every id a reply names is one of the person's
+// messages. No cloud, no key and no model call on Flow Framework's side: whatever the agent does with the
+// messages (its own model, its tools) runs on its side.
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { WHATSAPP, z } from "../../src/index.js";
+import { setting } from "../../src/traces.js";
+import { checkReply, postMessage, TurnError } from "./http-agent.js";
+import { packageRoot } from "./new.js";
+/** A 1×1 PNG. */
+const PHOTO = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+export const CASES = [
+    { id: "message", title: "a typed message", messages: [{ messageId: "m1", message: { text: "hi, what time are you open today?" } }] },
+    {
+        id: "double-text",
+        title: "two messages in a row, in one conversation",
+        messages: [
+            { messageId: "m1", message: { text: "can i get a large latte" } },
+            { messageId: "m2", message: { text: "oat milk actually" } },
+        ],
+    },
+    { id: "file", title: "a photo with no caption", messages: [{ messageId: "m1", message: { text: "", attachments: [{ kind: "image", mime: "image/png", name: "photo.png", data: PHOTO }] } }] },
+    {
+        id: "message-ids",
+        title: "a tapped button quoting the agent, with an id to react to",
+        messages: [
+            { messageId: "m1", message: { text: "do you have oat milk?" } },
+            { messageId: "m2", message: { text: "Oat", choice: { title: "Oat" }, replyTo: { text: "Which milk would you like?", fromAgent: true } } },
+        ],
+    },
+    { id: "no-reply", title: "a message that may need no answer", messages: [{ messageId: "m1", message: { text: "ok 👍" } }] },
+];
+const schemaFile = (name) => JSON.parse(readFileSync(join(packageRoot(), "spec", name), "utf8"));
+function schemas() {
+    const response = schemaFile("response.schema.json");
+    const shape = z.fromJSONSchema({ ...response, properties: { replies: { type: "array" } } });
+    // One schema per reply type, so a bad reply is reported against its own type.
+    const replies = new Map(Object.keys(response.$defs).map((type) => [type, z.fromJSONSchema({ $schema: response.$schema, $defs: response.$defs, $ref: `#/$defs/${type}` })]));
+    return { shape, replies };
+}
+const issues = (error, at) => error.issues.map((i) => `${[at, ...i.path].join(".")}: ${i.message}`).join("; ");
+/** Why this answer breaks the contract, or null. `ids` are the person's messages so far. */
+function problem(replies, ids, s) {
+    for (const [n, reply] of replies.entries()) {
+        const at = `replies[${n}]`;
+        const type = reply?.type;
+        const schema = typeof type === "string" ? s.replies.get(type) : undefined;
+        if (!schema)
+            return `${at}.type: must be one of ${[...s.replies.keys()].join(", ")}`;
+        const valid = schema.safeParse(reply);
+        if (!valid.success)
+            return issues(valid.error, at);
+        const shown = checkReply(reply, WHATSAPP);
+        if ("refused" in shown)
+            return `${at}: would not be sent on WhatsApp: ${shown.refused}`;
+        const r = reply;
+        for (const id of [r.replyTo, r.messageId, ...(r.messageIds ?? [])]) {
+            if (id !== undefined && !ids.includes(id))
+                return `${at} names ${JSON.stringify(id)}, which is not one of the person's messages (${ids.join(", ")})`;
+        }
+    }
+    return null;
+}
+const described = (answers) => answers
+    .map((a) => {
+    const types = a.replies.map((r) => String(r.type));
+    return `${a.messageId}: ${types.length ? `${types.length} ${types.length === 1 ? "reply" : "replies"} (${types.join(", ")})` : "no reply"}`;
+})
+    .join("; ");
+export async function checkEndpoint(options) {
+    const s = schemas();
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    // Fresh conversations on every check, in the cloud's form, so an endpoint that keeps history never mixes runs.
+    const session = `check_${randomBytes(4).toString("hex")}`;
+    const results = [];
+    for (const c of CASES) {
+        const conversationId = `whatsapp:${session}.${c.id}.whatsapp.1`;
+        const answers = [];
+        let failed = null;
+        for (const [n, { messageId, message }] of c.messages.entries()) {
+            let replies;
+            try {
+                replies = await postMessage(options, timeoutMs, { conversationId, messageId, channel: "whatsapp", message });
+            }
+            catch (error) {
+                failed = `${messageId}: ${error instanceof TurnError ? error.message : error.message}`;
+                break;
+            }
+            answers.push({ messageId, replies });
+            const wrong = problem(replies, c.messages.slice(0, n + 1).map((m) => m.messageId), s);
+            if (wrong) {
+                failed = `${messageId}: ${wrong}`;
+                break;
+            }
+        }
+        results.push({ id: c.id, title: c.title, pass: failed === null, detail: failed ?? described(answers), answers });
+    }
+    return results;
+}
+const USAGE = `Usage: flow check-endpoint <url> [--token-env NAME] [--agent-timeout <s>] [--json]
+
+Checks an agent's HTTP endpoint against Flow Framework's contract (spec/agent-endpoint.openapi.yaml) with
+a fixed set of synthetic messages. No cloud, no key, no model call on Flow Framework's side.
+
+  --token-env NAME     Send the value of NAME as authorization: Bearer <value>
+                       (default: FLOW_FRAMEWORK_AGENT_TOKEN, when it is set)
+  --agent-timeout <s>  How long one message waits for its answer (default: 60)
+  --json               Print the results as JSON
+
+Exit status: 0 when every case passed, 1 otherwise.`;
+/** The command: prints one line per case (or JSON) and returns the exit status. */
+export async function checkEndpointCli(args, env = process.env, print = console.log, printError = console.error) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, options: { "token-env": { type: "string" }, "agent-timeout": { type: "string", default: "60" }, json: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } } });
+    }
+    catch (error) {
+        printError(`${error.message}\n\n${USAGE}`);
+        return 1;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        print(USAGE);
+        return 0;
+    }
+    const url = positionals.length === 1 ? positionals[0] : "";
+    if (!/^https?:\/\/[^/]/.test(url) || !URL.canParse(url)) {
+        printError(`check-endpoint takes one http:// or https:// URL, such as http://localhost:3000/flow.\n\n${USAGE}`);
+        return 1;
+    }
+    const timeout = Number(values["agent-timeout"]);
+    if (!(timeout > 0)) {
+        printError("--agent-timeout must be a number of seconds above 0.");
+        return 1;
+    }
+    const tokenEnv = values["token-env"];
+    const token = (tokenEnv ? env[tokenEnv] : setting("AGENT_TOKEN", env)) || undefined;
+    if (tokenEnv && !token) {
+        printError(`${tokenEnv} is not set.`);
+        return 1;
+    }
+    const results = await checkEndpoint({ url, token, timeoutMs: timeout * 1000 });
+    const passed = results.filter((r) => r.pass).length;
+    if (values.json)
+        print(JSON.stringify({ url, passed: passed === results.length, cases: results }, null, 2));
+    else {
+        for (const r of results)
+            print(`${r.pass ? "PASS" : "FAIL"}  ${r.id} (${r.title}): ${r.detail}`);
+        print(`\n${passed} of ${results.length} cases passed.`);
+    }
+    return passed === results.length ? 0 : 1;
+}

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/testing/src/chinwag.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The `chinwag` command from before the rename, kept for one release: it says so on stderr (stdout
+// stays the report's, for --json), then runs the flow command (testing/src/cli.ts) as it is.
+console.error("chinwag is now Flow Framework (@flow-engineer/flow): run npx @flow-engineer/flow, and npm i @flow-engineer/flow.");
+await import("./cli.js");
+export {};

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};