@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/testing/src/flow-login.d.ts

@@ -0,0 +1,143 @@
+export declare const LOGIN_URL = "https://flow.engineer";
+/** The longest one request to flow.engineer may take; login's polls are cut shorter by what is left of --timeout. */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** A login URL a token may go to: https, or http to this machine only (a local flow.engineer). */
+export declare function safeLoginUrl(url: string): boolean;
+/** flow.engineer, or FLOW_FRAMEWORK_LOGIN_URL, without trailing slashes (trimmed from the end, in linear time). */
+export declare function loginUrl(env?: NodeJS.ProcessEnv): string;
+/** ~/.config/flow-framework/credentials.json (XDG_CONFIG_HOME when set), written at mode 0600. */
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+export interface Credentials {
+    token: string;
+    expires_at?: string;
+    /** The server that issued it, so logout revokes it there. */
+    url: string;
+}
+/**
+ * The token to use: FLOW_FRAMEWORK_TOKEN, else the credentials file's (with `url`, the server that
+ * issued it, the only one it is sent to); undefined when signed out.
+ */
+export declare function currentToken(env?: NodeJS.ProcessEnv): {
+    token: string;
+    from: "env" | "file";
+    url?: string;
+} | undefined;
+export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials | undefined;
+export declare function saveCredentials(credentials: Credentials, env?: NodeJS.ProcessEnv): string;
+export declare function deleteCredentials(env?: NodeJS.ProcessEnv): boolean;
+/** A device code started by `flow login` and not approved yet, kept for `flow login --wait`. */
+export interface PendingLogin extends DeviceStart {
+    /** When the code expires, in ms since the epoch. */
+    expires_at: number;
+    /** The server that issued it. */
+    url: string;
+}
+/** ~/.config/flow-framework/pending.json, written at mode 0600 and deleted once the code is used or expired. */
+export declare function pendingPath(env?: NodeJS.ProcessEnv): string;
+export declare function readPending(env?: NodeJS.ProcessEnv): PendingLogin | undefined;
+export declare function savePending(pending: PendingLogin, env?: NodeJS.ProcessEnv): void;
+export declare function deletePending(env?: NodeJS.ProcessEnv): void;
+export interface DeviceStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    interval: number;
+    expires_in: number;
+}
+export type TokenAnswer = {
+    status: "signed_in";
+    token: string;
+    expires_at?: string;
+    account?: Account;
+} | {
+    status: "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
+};
+export interface Account {
+    email: string;
+    account: string;
+}
+export interface SetupAnswer {
+    agent_id: string;
+    /** Only the keys minted in this call come back (those the request did not say it has). */
+    cloud_key?: string;
+    traces_key?: string;
+    messaging_key?: string;
+    /** Each channel's shared sender and phone link, only while Flow has that channel open. */
+    telegram_sender?: string;
+    whatsapp_sender?: string;
+    imessage_sender?: string;
+    whatsapp_link?: string;
+    imessage_link?: string;
+    /** Missing only when the server could not make one; the keys it minted are written anyway. */
+    join_code?: string;
+    account?: Account;
+    app_id?: string;
+    dashboard_url?: string;
+    /** The flow.engineer page that opens Telegram with the join message filled in. */
+    try_url?: string;
+    telegram_link?: string;
+    /** The try page per channel with a sender: {telegram: ".../try/<code>?c=telegram", ...}. */
+    try_urls?: Record<string, string>;
+    /** The account's free-trial counts per channel; limit null is unlimited. iMessage also counts the people it may reach. */
+    trial?: Record<string, {
+        limit: number | null;
+        used: number;
+        contacts?: {
+            limit: number;
+            used: number;
+        };
+    }>;
+    /** The answer fields of the keys made in this call. */
+    minted?: string[];
+    next?: string[];
+    /** Up to 20 lines for the owner, shown as they are. */
+    warnings?: string[];
+}
+/** The answer's warnings: its strings only, at most 20. */
+export declare function warningsOf(body: Record<string, unknown>): string[];
+/** Retry-After as seconds from now (delta-seconds or an HTTP date); undefined when absent or unreadable. */
+export declare function retryAfterSeconds(header: string | null, now?: number): number | undefined;
+/**
+ * The server answered with an error status; `code` is its `error` field when it gave one, `next` its
+ * next step, and `fields` the whole answer (a failed setup carries the keys it minted anyway).
+ */
+export declare class LoginRefused extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly next: string | undefined;
+    readonly fields: Record<string, unknown>;
+    /** Seconds the server asked to wait (Retry-After), for a 429. */
+    readonly retryAfter: number | undefined;
+    constructor(status: number, code: string, message: string, next?: string, fields?: Record<string, unknown>, retryAfter?: number);
+}
+/** The server answered nothing in time: `ms` is how long this request was given. */
+export declare class TimedOut extends Error {
+    readonly ms: number;
+    constructor(url: string, ms: number);
+}
+/** `clientName` and `hostname` are shown on the approval page. */
+export declare function startDevice(url: string, clientName: string, hostname: string): Promise<DeviceStart>;
+/** `timeoutMs` cuts this one poll short (login gives it what is left of --timeout). */
+export declare function pollToken(url: string, deviceCode: string, timeoutMs?: number): Promise<TokenAnswer>;
+export declare function revoke(url: string, token: string): Promise<void>;
+export declare function whoami(url: string, token: string): Promise<Account>;
+export declare function setup(url: string, token: string, request: {
+    name: string;
+    hostname: string;
+    channels: string[];
+    have: string[];
+}): Promise<SetupAnswer>;
+/** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
+export declare const SETUP_ENV: {
+    readonly cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY";
+    readonly traces_key: "FLOW_FRAMEWORK_TRACES_KEY";
+    readonly messaging_key: "FLOW_MESSAGING_KEY";
+    readonly telegram_sender: "FLOW_MESSAGING_TELEGRAM_SENDER";
+    readonly whatsapp_sender: "FLOW_MESSAGING_WHATSAPP_SENDER";
+    readonly imessage_sender: "FLOW_MESSAGING_IMESSAGE_SENDER";
+    readonly join_code: "FLOW_FRAMEWORK_JOIN_CODE";
+    readonly try_url: "FLOW_FRAMEWORK_TRY_URL";
+};
+/** The phone link for a join code, built as the server builds its try_url, for a .env from before setup kept it. */
+export declare function tryLink(url: string, joinCode: string, channel: string): string;

package/dist/testing/src/flow-login.js

@@ -0,0 +1,249 @@
+// The flow.engineer side of `flow login`, `logout`, `whoami` and `setup`: every call to it, and
+// where the Flow CLI token is kept. Only this file knows the server's routes and field names
+// (flow.engineer's CLI sign-in contract).
+//   POST /cli/device {client_name, hostname}  -> {device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in}
+//   POST /cli/token {device_code}             -> {access_token, expires_at, account}, or 400 {error} as RFC 8628 has it:
+//                                                authorization_pending, slow_down, expired_token, access_denied, invalid_grant
+//   POST /cli/revoke (bearer) {}              ends this token
+//   GET  /cli/whoami (bearer)                 -> {account, email, token}
+//   POST /cli/setup (bearer) {name, hostname, channels, have}
+//        -> {agent_id, cloud_key?, traces_key?, messaging_key?, join_code, account, app_id, dashboard_url, try_url,
+//            <channel>_sender?, <channel>_link? (telegram, whatsapp, imessage: each only while that shared sender
+//            is open), try_urls?, trial?, minted, next}; a 502 carries every field that worked too;
+//        429 slow_down with Retry-After; 403 for a trial limit (sandbox_allowance_used, ...), its next prose
+//        Any answer may carry warnings: up to 20 strings to show the owner as they are.
+// Every error is flat: {"error": "<code>", "error_description": "<sentence>", "next": "<command, URL or sentence>"}.
+// The token is opaque (fcli_...), good only for /cli/*, and sent only to the server that issued it,
+// over https (http only to this machine). Every request gives up after REQUEST_TIMEOUT_MS at most.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, configFile, RUN, setting } from "../../src/names.js";
+export const LOGIN_URL = "https://flow.engineer";
+/** The longest one request to flow.engineer may take; login's polls are cut shorter by what is left of --timeout. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** A login URL a token may go to: https, or http to this machine only (a local flow.engineer). */
+export function safeLoginUrl(url) {
+    const parsed = URL.parse(url);
+    if (!parsed)
+        return false;
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+}
+/** flow.engineer, or FLOW_FRAMEWORK_LOGIN_URL, without trailing slashes (trimmed from the end, in linear time). */
+export function loginUrl(env = process.env) {
+    const url = setting("LOGIN_URL", env) || LOGIN_URL;
+    let end = url.length;
+    while (end > 0 && url[end - 1] === "/")
+        end--;
+    return url.slice(0, end);
+}
+/** ~/.config/flow-framework/credentials.json (XDG_CONFIG_HOME when set), written at mode 0600. */
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), "credentials.json");
+}
+/** The credentials file to read or delete: credentialsPath, else ~/.config/chinwag/credentials.json while only it exists. */
+const savedCredentialsPath = (env) => configFile("credentials.json", env);
+/**
+ * The token to use: FLOW_FRAMEWORK_TOKEN, else the credentials file's (with `url`, the server that
+ * issued it, the only one it is sent to); undefined when signed out.
+ */
+export function currentToken(env = process.env) {
+    const fromEnv = setting("TOKEN", env)?.trim();
+    if (fromEnv)
+        return { token: fromEnv, from: "env" };
+    const saved = readCredentials(env);
+    return saved ? { token: saved.token, from: "file", url: saved.url || LOGIN_URL } : undefined;
+}
+export function readCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const saved = JSON.parse(readFileSync(path, "utf8"));
+        return typeof saved.token === "string" && saved.token ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600); // a file that was already there keeps its mode on write
+    return path;
+}
+export function deleteCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** ~/.config/flow-framework/pending.json, written at mode 0600 and deleted once the code is used or expired. */
+export function pendingPath(env = process.env) {
+    return join(configDir(env), "pending.json");
+}
+export function readPending(env = process.env) {
+    try {
+        const saved = JSON.parse(readFileSync(pendingPath(env), "utf8"));
+        return typeof saved.device_code === "string" && typeof saved.expires_at === "number" ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function savePending(pending, env = process.env) {
+    const path = pendingPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(pending, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function deletePending(env = process.env) {
+    rmSync(pendingPath(env), { force: true });
+}
+/** The answer's warnings: its strings only, at most 20. */
+export function warningsOf(body) {
+    return Array.isArray(body.warnings) ? body.warnings.filter((w) => typeof w === "string" && w !== "").slice(0, 20) : [];
+}
+/** Retry-After as seconds from now (delta-seconds or an HTTP date); undefined when absent or unreadable. */
+export function retryAfterSeconds(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const value = header.trim();
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - now) / 1000));
+}
+/**
+ * The server answered with an error status; `code` is its `error` field when it gave one, `next` its
+ * next step, and `fields` the whole answer (a failed setup carries the keys it minted anyway).
+ */
+export class LoginRefused extends Error {
+    status;
+    code;
+    next;
+    fields;
+    /** Seconds the server asked to wait (Retry-After), for a 429. */
+    retryAfter;
+    constructor(status, code, message, next, fields = {}, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.next = next;
+        this.fields = fields;
+        this.retryAfter = retryAfter;
+    }
+}
+/** The server answered nothing in time: `ms` is how long this request was given. */
+export class TimedOut extends Error {
+    ms;
+    constructor(url, ms) {
+        super(`${url} did not answer within ${Math.ceil(ms / 1000)} s.`);
+        this.ms = ms;
+    }
+}
+async function call(url, path, options = {}) {
+    if (!safeLoginUrl(url)) {
+        throw new LoginRefused(0, "insecure_login_url", `${url} is not https: the sign-in and its token go only over https (http only to localhost).`, `set FLOW_FRAMEWORK_LOGIN_URL to an https address, or unset it to use ${LOGIN_URL}`);
+    }
+    const timeoutMs = Math.max(0, Math.min(options.timeoutMs ?? REQUEST_TIMEOUT_MS, REQUEST_TIMEOUT_MS));
+    const headers = { accept: "application/json" };
+    if (options.token)
+        headers.authorization = `Bearer ${options.token}`;
+    if (options.body !== undefined)
+        headers["content-type"] = "application/json";
+    let response;
+    let text;
+    try {
+        response = await fetch(`${url}${path}`, {
+            method: options.method ?? "POST",
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            redirect: options.token ? "error" : "follow", // a redirect would carry the token to another address
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        if (error.name === "TimeoutError")
+            throw new TimedOut(url, timeoutMs);
+        throw error;
+    }
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        if (response.ok)
+            throw new LoginRefused(response.status, "bad_answer", `${url}${path} answered ${response.status} with no JSON.`);
+    }
+    return { status: response.status, body, retryAfter: retryAfterSeconds(response.headers.get("retry-after")) };
+}
+function refused(path, answer, url) {
+    // A bare 404: this server has no CLI sign-in (an older one, or not flow.engineer at all).
+    if (answer.status === 404 && typeof answer.body.error !== "string") {
+        return new LoginRefused(404, "server_unsupported", `${url} has no ${path}, so it cannot sign in the Flow CLI: it is an older server, or not flow.engineer.`, url === LOGIN_URL ? `${RUN}@latest login` : `unset FLOW_FRAMEWORK_LOGIN_URL to use ${LOGIN_URL}, or point it at a server that has /cli/`, answer.body);
+    }
+    const code = typeof answer.body.error === "string" ? answer.body.error : answer.status === 401 ? "not_signed_in" : `http_${answer.status}`;
+    const detail = typeof answer.body.error_description === "string" ? answer.body.error_description : typeof answer.body.message === "string" ? answer.body.message : "";
+    const next = typeof answer.body.next === "string" && answer.body.next ? answer.body.next : undefined;
+    const sentence = detail.endsWith(".") ? detail.slice(0, -1) : detail;
+    return new LoginRefused(answer.status, code, `${path} answered ${answer.status} ${code}${sentence ? `: ${sentence}` : ""}.`, next, answer.body, answer.retryAfter);
+}
+/** `clientName` and `hostname` are shown on the approval page. */
+export async function startDevice(url, clientName, hostname) {
+    const answer = await call(url, "/cli/device", { body: { client_name: clientName, hostname } });
+    if (answer.status !== 200 || typeof answer.body.device_code !== "string")
+        throw refused("/cli/device", answer, url);
+    return answer.body;
+}
+const WAITING = new Set(["authorization_pending", "slow_down", "expired_token", "access_denied"]);
+/** `timeoutMs` cuts this one poll short (login gives it what is left of --timeout). */
+export async function pollToken(url, deviceCode, timeoutMs) {
+    const answer = await call(url, "/cli/token", { body: { device_code: deviceCode }, timeoutMs });
+    const token = answer.body.access_token;
+    if (answer.status === 200 && typeof token === "string") {
+        return { status: "signed_in", token, expires_at: answer.body.expires_at, account: answer.body.account };
+    }
+    const error = answer.body.error;
+    if (typeof error === "string" && WAITING.has(error))
+        return { status: error };
+    throw refused("/cli/token", answer, url);
+}
+export async function revoke(url, token) {
+    const answer = await call(url, "/cli/revoke", { token, body: {} });
+    // 401: the token had already ended, which is what logout wants.
+    if (answer.status >= 300 && answer.status !== 401)
+        throw refused("/cli/revoke", answer, url);
+}
+export async function whoami(url, token) {
+    const answer = await call(url, "/cli/whoami", { token, method: "GET" });
+    if (answer.status !== 200)
+        throw refused("/cli/whoami", answer, url);
+    return answer.body;
+}
+export async function setup(url, token, request) {
+    const answer = await call(url, "/cli/setup", { token, body: request });
+    // A 200 is returned whole even without a join code: the keys it minted are shown only now.
+    if (answer.status !== 200)
+        throw refused("/cli/setup", answer, url);
+    return answer.body;
+}
+/** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
+export const SETUP_ENV = {
+    cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY",
+    traces_key: "FLOW_FRAMEWORK_TRACES_KEY",
+    messaging_key: "FLOW_MESSAGING_KEY",
+    telegram_sender: "FLOW_MESSAGING_TELEGRAM_SENDER",
+    whatsapp_sender: "FLOW_MESSAGING_WHATSAPP_SENDER",
+    imessage_sender: "FLOW_MESSAGING_IMESSAGE_SENDER",
+    join_code: "FLOW_FRAMEWORK_JOIN_CODE",
+    try_url: "FLOW_FRAMEWORK_TRY_URL",
+};
+/** The phone link for a join code, built as the server builds its try_url, for a .env from before setup kept it. */
+export function tryLink(url, joinCode, channel) {
+    return `${url}/try/${encodeURIComponent(joinCode)}?c=${encodeURIComponent(channel)}`;
+}

package/dist/testing/src/http-agent.d.ts

@@ -0,0 +1,47 @@
+import { type ChannelInfo, type ChannelSummary, type Deliver, type EventSink, type Incoming, type Outbound, type ReceiveOptions } from "../../src/index.ts";
+export interface HttpAgentOptions {
+    url: string;
+    /** Sent as `authorization: Bearer <token>` (FLOW_FRAMEWORK_AGENT_TOKEN). */
+    token?: string;
+    /** The channel every message names; default the platform the run plays (whatsapp, sms, imessage, telegram, web). */
+    channel?: string;
+    /** How long one message waits for its answer. Default 60 s. */
+    timeoutMs?: number;
+    events?: EventSink[];
+    log?: (line: string) => void;
+}
+/** The person's message as the agent's endpoint gets it. */
+export interface HttpAgentRequest {
+    conversationId: string;
+    /** The id the cloud gave this message (m1, m2, ...): a reply's replyTo, a reaction's or a read's messageId. */
+    messageId: string;
+    channel: string;
+    message: {
+        text: string;
+        replyTo?: Incoming["replyTo"];
+        choice?: Incoming["choice"];
+        attachments?: Array<{
+            kind: "image" | "audio" | "document";
+            mime: string;
+            name?: string;
+            data: string;
+        }>;
+    };
+}
+export declare class TurnError extends Error {
+}
+/** POSTs one message and returns its replies, unchecked; throws a TurnError saying why when the answer fails the turn. */
+export declare function postMessage(options: Pick<HttpAgentOptions, "url" | "token">, timeoutMs: number, body: HttpAgentRequest): Promise<unknown[]>;
+/** The reply as the platform takes it, or why it cannot go: the checks a Flow Framework agent's send gets. */
+export declare function checkReply(reply: unknown, info: ChannelInfo): {
+    outbound: Outbound;
+} | {
+    refused: string;
+};
+export declare function httpAgent(options: HttpAgentOptions): {
+    /** None of its own: each run plays its platform as the platform is. */
+    channels(): ChannelSummary[];
+    receive(conversationId: string, message: string | Incoming, deliver: Deliver, receive?: ReceiveOptions): string | null;
+    /** The person reacted to one of its messages: not sent to the endpoint in this version. */
+    reacted(_conversationId: string, _emoji: string, _toText: string): void;
+};

package/dist/testing/src/http-agent.js

@@ -0,0 +1,155 @@
+// An agent you already have, on any framework, tested through its HTTP endpoint: `flow test
+// --agent-url <url>`. This plays the part of a Flow Framework Agent on the developer's machine: each of the
+// person's messages is one POST to the URL from here (so the agent never has to be reachable from
+// the internet), and the replies it answers go to the test cloud as a Flow Framework agent's would. Its own
+// tools run on its side, for real.
+//
+//   POST <url>  { conversationId, messageId, channel, message: { text, attachments?: [{ kind, mime, name?, data }] } }
+//   200         { replies: Outbound[] }        (data is base64; [] is no reply)
+//
+// A conversation's messages go one at a time, in order: the next is sent once the last one's answer
+// is in. Each reply is checked against what the run's platform can show, as a Flow Framework agent's send
+// is. Agents that answer later (through a callback) are not supported yet.
+import { Buffer } from "node:buffer";
+import { emitter } from "../../src/events.js";
+import { fitMessage, z } from "../../src/index.js";
+import { sendInput, sendRefusal } from "../../src/talk.js";
+const answerSchema = z.object({ replies: z.array(z.unknown()) });
+const otherReply = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("read"), messageIds: z.array(z.string()) }),
+    z.object({ type: z.literal("reaction"), emoji: z.string().min(1), messageId: z.string().min(1) }),
+    z.looseObject({ type: z.literal("template"), name: z.string().min(1) }),
+    z.object({ type: z.literal("status"), text: z.string().nullable() }),
+    z.object({ type: z.literal("typing"), on: z.boolean() }),
+]);
+export class TurnError extends Error {
+}
+const problems = (error) => error.issues.map((i) => (i.code === "unrecognized_keys" ? `${i.keys.join(", ")}: not something this platform shows` : (i.path.length ? `${i.path.join(".")}: ` : "") + i.message)).join("; ");
+/** POSTs one message and returns its replies, unchecked; throws a TurnError saying why when the answer fails the turn. */
+export async function postMessage(options, timeoutMs, body) {
+    let response;
+    let text;
+    try {
+        response = await fetch(options.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        const e = error;
+        if (e.name === "TimeoutError")
+            throw new TurnError(`no answer from ${options.url} within ${timeoutMs / 1000} s`);
+        throw new TurnError(`could not reach ${options.url}: ${e.cause?.code ?? e.cause?.message ?? e.message}`);
+    }
+    if (response.status !== 200)
+        throw new TurnError(`${options.url} answered ${response.status}${text.trim() ? `: ${text.trim().slice(0, 200)}` : ""}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new TurnError(`${options.url} answered 200 with a body that is not JSON: ${text.slice(0, 200)}`);
+    }
+    const answer = answerSchema.safeParse(parsed);
+    if (!answer.success)
+        throw new TurnError(`${options.url} answered 200 without { "replies": [...] }: ${text.slice(0, 200)}`);
+    return answer.data.replies;
+}
+/** The reply as the platform takes it, or why it cannot go: the checks a Flow Framework agent's send gets. */
+export function checkReply(reply, info) {
+    const type = reply?.type;
+    if (type !== "message") {
+        const other = otherReply.safeParse(reply);
+        return other.success ? { outbound: other.data } : { refused: problems(other.error) };
+    }
+    const { type: _, replyTo, fields, ...rest } = reply;
+    const input = { ...rest, ...(replyTo !== undefined ? { reply_to: replyTo } : {}) };
+    const sent = sendInput(info).strict().safeParse(input);
+    if (!sent.success)
+        return { refused: problems(sent.error).replaceAll("reply_to", "replyTo") };
+    if (fields !== undefined && (typeof fields !== "object" || fields === null || Array.isArray(fields)))
+        return { refused: "fields: must be an object" };
+    const refusal = sendRefusal(info, input);
+    if (refusal)
+        return { refused: refusal };
+    return { outbound: fitMessage(info, { type: "message", ...rest, ...(replyTo !== undefined ? { replyTo } : {}), ...(fields ? { fields } : {}) }) };
+}
+export function httpAgent(options) {
+    const emit = emitter(options.events ?? []);
+    const log = options.log ?? ((line) => console.log(line));
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    /** Each conversation's last message, so the next one waits for its answer. */
+    const queues = new Map();
+    async function turn(conversationId, request, incoming, info, deliver) {
+        const started = Date.now();
+        emit(conversationId, "turn.start", {});
+        try {
+            if (incoming.attachments?.length) {
+                request.message.attachments = await Promise.all(incoming.attachments.map(async (a) => ({ kind: a.kind, mime: a.mime, ...(a.name ? { name: a.name } : {}), data: Buffer.from(await a.data()).toString("base64") })));
+            }
+            for (const reply of await postMessage(options, timeoutMs, request)) {
+                const checked = checkReply(reply, info);
+                const text = reply?.text;
+                const shown = typeof text === "string" ? text : `(${String(reply?.type ?? "reply")})`;
+                if ("refused" in checked) {
+                    log(`${conversationId}: a reply was not sent: ${checked.refused}`);
+                    emit(conversationId, "message.undelivered", { text: shown, reason: checked.refused });
+                    continue;
+                }
+                const outbound = checked.outbound;
+                try {
+                    await deliver(outbound);
+                }
+                catch (error) {
+                    emit(conversationId, "message.undelivered", { text: shown, reason: error.message });
+                    continue;
+                }
+                if (outbound.type === "message") {
+                    const { type: _, ...sent } = outbound;
+                    emit(conversationId, "message.out", { ...sent, channel: request.channel });
+                }
+                else if (outbound.type === "reaction") {
+                    emit(conversationId, "reaction", { emoji: outbound.emoji, messageId: outbound.messageId });
+                }
+            }
+        }
+        catch (error) {
+            const reason = error instanceof TurnError ? error.message : `the message could not be sent: ${error.message}`;
+            log(`${conversationId}: ${reason}`);
+            emit(conversationId, "model.error", { error: reason });
+            emit(conversationId, "message.undelivered", { text: "(the agent's answer)", reason });
+        }
+        finally {
+            emit(conversationId, "turn.end", { ms: Date.now() - started });
+        }
+    }
+    return {
+        /** None of its own: each run plays its platform as the platform is. */
+        channels() {
+            return [];
+        },
+        receive(conversationId, message, deliver, receive = {}) {
+            const incoming = typeof message === "string" ? { text: message } : message;
+            const messageId = receive.messageId ?? "";
+            // The cloud's conversations are "<platform>:<person>".
+            const channel = options.channel ?? /^([a-z]+):/.exec(conversationId)?.[1] ?? "chat";
+            const request = {
+                conversationId,
+                messageId,
+                channel,
+                message: { text: incoming.text, ...(incoming.replyTo ? { replyTo: incoming.replyTo } : {}), ...(incoming.choice ? { choice: incoming.choice } : {}) },
+            };
+            const attachments = incoming.attachments?.map((a) => ({ kind: a.kind, mime: a.mime, ...(a.name ? { name: a.name } : {}) }));
+            emit(conversationId, "message.in", { text: incoming.text, messageId, channel, ...(attachments ? { attachments } : {}) });
+            const info = receive.channel ?? { reactions: false, status: false };
+            const next = (queues.get(conversationId) ?? Promise.resolve()).then(() => turn(conversationId, request, incoming, info, deliver));
+            queues.set(conversationId, next);
+            return messageId || null;
+        },
+        /** The person reacted to one of its messages: not sent to the endpoint in this version. */
+        reacted(_conversationId, _emoji, _toText) { },
+    };
+}

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

@@ -0,0 +1,3 @@
+export { runInCloud, type CloudSummary, type ConnectOptions } from "./client.ts";
+export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash, type Scenario, type SuiteFile, type ToolFile } from "./suite.ts";
+export type { Check, Command, OpenSession, Opened, RunKey, RunSummary, SessionSummary, ToolCallRequest, ToolCallResult, UploadFile, Usage, WireIncoming } from "./protocol.ts";

package/dist/testing/src/index.js

@@ -0,0 +1,2 @@
+export { runInCloud } from "./client.js";
+export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash } from "./suite.js";

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

@@ -0,0 +1,13 @@
+/** Throws unless `name` can be an agent's folder and package name. */
+export declare function checkName(name: string): void;
+/** The @flow-engineer/flow package's folder: the root of a clone, or the installed package. */
+export declare function packageRoot(from?: string): string;
+/** Makes `<into>/<name>` (the current folder by default) and returns it. */
+export declare function newStandalone(name: string, options?: {
+    into?: string;
+    root?: string;
+}): string;
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export declare function initHere(dir?: string, options?: {
+    root?: string;
+}): string;