@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/testing/src/new.js

@@ -0,0 +1,147 @@
+// `flow new <name>`: makes ./<name>/, an agent of its own started from the café example (Pip),
+// that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow",
+// "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
+// skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
+// `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
+// makes agents/<name>/ instead.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** Throws unless `name` can be an agent's folder and package name. */
+export function checkName(name) {
+    if (!NAME.test(name))
+        throw new Error(`"${name}" is not a usable name: use lowercase letters, digits and dashes, such as my-agent.`);
+}
+/** The @flow-engineer/flow package's folder: the root of a clone, or the installed package. */
+export function packageRoot(from = dirname(fileURLToPath(import.meta.url))) {
+    for (let dir = from;; dir = dirname(dir)) {
+        const file = join(dir, "package.json");
+        if (existsSync(file) && JSON.parse(readFileSync(file, "utf8")).name === "@flow-engineer/flow")
+            return dir;
+        if (dirname(dir) === dir)
+            throw new Error("flow: can't find its own package.json");
+    }
+}
+const TSCONFIG = {
+    compilerOptions: {
+        target: "es2023",
+        module: "nodenext",
+        moduleResolution: "nodenext",
+        strict: true,
+        noEmit: true,
+        allowImportingTsExtensions: true,
+        erasableSyntaxOnly: true,
+        verbatimModuleSyntax: true,
+        skipLibCheck: true,
+        types: ["node"],
+    },
+    include: ["src"],
+};
+const ENV_EXAMPLE = `# One model key. The first line with a value is the one used.
+# Make it at the provider, then paste it here. Never commit this file.
+#   OPENROUTER_API_KEY   https://openrouter.ai/keys
+#   OPENAI_API_KEY       https://platform.openai.com/api-keys
+#   ANTHROPIC_API_KEY    https://console.anthropic.com/settings/keys
+#   GEMINI_API_KEY       https://aistudio.google.com/apikey
+OPENROUTER_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+
+# Optional. The model id for that provider; empty is that provider's default.
+# CAFE_MODEL=
+
+# The test cloud (npx @flow-engineer/flow test --synthetic) and traces. Sign in at https://flow.engineer/observe,
+# add the agent, and on its Developers page make a CI key (oci_..., shown once); the trace key is
+# from the same site.
+FLOW_FRAMEWORK_CLOUD=https://flow.engineer/observe
+FLOW_FRAMEWORK_CLOUD_KEY=
+FLOW_FRAMEWORK_TRACES_URL=https://flow.engineer/observe
+FLOW_FRAMEWORK_TRACES_KEY=
+`;
+const agentsMd = (name) => `# ${name}
+
+A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example (Pip).
+
+- Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent, \`flow-framework-tools\`
+  for its tools and their test files, \`flow-framework-tests\` for its test scenarios.
+- \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
+- The owner puts one model key in \`.env\` (never read or print it): \`OPENROUTER_API_KEY\`,
+  \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`. Then \`npx @flow-engineer/flow chat\`
+  talks to it in the terminal, \`npm start\` runs it in the playground, and \`npx @flow-engineer/flow link\`
+  signs in, puts its other keys in \`.env\` and prints the link that reaches it from a phone while
+  \`npm start\` runs. \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the
+  tests in the test cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\`
+  (\`npx @flow-engineer/flow --help\`).
+- The guide for coding agents, with exit codes and next steps: https://github.com/flow-engineer/flow/blob/main/docs/agents.md
+`;
+/** Makes `<into>/<name>` (the current folder by default) and returns it. */
+export function newStandalone(name, options = {}) {
+    checkName(name);
+    const dir = join(options.into ?? process.cwd(), name);
+    if (existsSync(dir))
+        throw new Error(`${dir} already exists: pick another name or remove it.`);
+    makeAgent(dir, name, options.root ?? packageRoot());
+    return dir;
+}
+/** What `flow init` writes into a folder; it refuses a folder that holds any of them, so nothing is overwritten. */
+const MADE = ["package.json", "tsconfig.json", "src", "agent", "tests", ".env.example", "AGENTS.md", "CLAUDE.md", ".npmrc"];
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export function initHere(dir = process.cwd(), options = {}) {
+    const taken = MADE.filter((f) => existsSync(join(dir, f)));
+    if (taken.length)
+        throw new Error(`${dir} has ${taken.join(", ")} already: run flow init in an empty folder, or flow new <name> to make one.`);
+    const name = basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "my-agent";
+    makeAgent(dir, name, options.root ?? packageRoot());
+    return name;
+}
+function makeAgent(dir, name, root) {
+    const cafe = join(root, "examples", "cafe");
+    for (const part of ["agent", "src", "tests"])
+        cpSync(join(cafe, part), join(dir, part), { recursive: true });
+    for (const file of readdirSync(join(dir, "src"), { recursive: true, encoding: "utf8" }).filter((f) => f.endsWith(".ts"))) {
+        const path = join(dir, "src", file);
+        const source = readFileSync(path, "utf8")
+            .replace(/(["'])(\.\.\/)+src\/index\.ts\1/g, '"@flow-engineer/flow"')
+            .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"')
+            .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"');
+        if (/["']\.\.\/\.\.\//.test(source))
+            throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
+        writeFileSync(path, source);
+    }
+    const own = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const pkg = {
+        name,
+        version: "0.1.0",
+        private: true,
+        description: `${name}: a Flow Framework agent, started from the café example.`,
+        type: "module",
+        engines: own.engines,
+        scripts: { start: "node --env-file-if-exists=.env src/main.ts", test: "flow test", typecheck: "tsc --noEmit" },
+        dependencies: { "@flow-engineer/flow": `^${own.version}` },
+        devDependencies: { "@types/node": own.devDependencies["@types/node"], typescript: own.devDependencies.typescript },
+    };
+    writeFileSync(join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+    writeFileSync(join(dir, "tsconfig.json"), `${JSON.stringify(TSCONFIG, null, 2)}\n`);
+    // An existing .gitignore (flow init in a fresh repository) keeps its lines and gets the missing ones.
+    const ignore = join(dir, ".gitignore");
+    const ignored = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    const missing = ["node_modules/", ".env", ".flow/"].filter((line) => !ignored.split("\n").includes(line));
+    if (missing.length)
+        writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
+    // npm install then refuses a Node older than the engines field says, before .ts files fail to load.
+    writeFileSync(join(dir, ".npmrc"), "engine-strict=true\n");
+    writeFileSync(join(dir, ".env.example"), ENV_EXAMPLE);
+    const skills = join(root, "coding-agents");
+    for (const file of readdirSync(skills).filter((f) => f.endsWith(".md"))) {
+        const text = readFileSync(join(skills, file), "utf8");
+        const skill = /^name:\s*(\S+)\s*$/m.exec(text)?.[1];
+        if (!skill)
+            throw new Error(`flow: coding-agents/${file} has no name in its front matter.`);
+        mkdirSync(join(dir, ".claude", "skills", skill), { recursive: true });
+        writeFileSync(join(dir, ".claude", "skills", skill, "SKILL.md"), text);
+    }
+    writeFileSync(join(dir, "AGENTS.md"), agentsMd(name));
+    writeFileSync(join(dir, "CLAUDE.md"), "@AGENTS.md\n");
+}

package/dist/testing/src/print-run.d.ts

@@ -0,0 +1,3 @@
+import type { RunSummary } from "./protocol.ts";
+/** Prints each run once. A run already shown as it finished is not printed again with the summary. */
+export declare function runPrinter(log?: (line: string) => void): (run: RunSummary) => void;

package/dist/testing/src/print-run.js

@@ -0,0 +1,22 @@
+import { runVerdict } from "./report.js";
+const usd = (n) => `$${n.toFixed(4)}`;
+/** Prints each run once. A run already shown as it finished is not printed again with the summary. */
+export function runPrinter(log = console.log) {
+    const printed = new Set();
+    return (r) => {
+        if (printed.has(r.runId))
+            return;
+        printed.add(r.runId);
+        const verdict = runVerdict(r);
+        const gaveUp = verdict === "passed" && r.ended === "gave_up" ? " (passed, the person gave up)" : "";
+        const retried = r.retried ? "; tried once more" : "";
+        // An errored run: the cloud could not play or judge it, so its checks say nothing about the agent.
+        const error = verdict === "errored" ? `; error: ${r.error ?? r.ended} (the cloud could not play or judge this run, not the agent's fault)` : "";
+        const label = verdict === "errored" ? "ERROR" : verdict === "passed" ? "PASS" : "FAIL";
+        log(`${label}  ${r.scenario} #${r.run} (${r.channel}) ${r.runId}: ${r.turns} turn${r.turns === 1 ? "" : "s"}, ended: ${r.ended}${gaveUp}${retried}${error}; slowest acknowledgement ${r.slowestAckMs === null ? "never" : `${r.slowestAckMs} ms`}; cost ${usd(r.agentUsage.costUsd)} agent + ${usd(r.testUsage.costUsd)} test`);
+        if (verdict !== "errored")
+            for (const c of r.checks.filter((c) => !c.pass))
+                log(`      ✗ ${c.kind}: ${c.text}\n        ${c.reason}`);
+        log(`      watch: ${r.watch}`);
+    };
+}

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

@@ -0,0 +1,159 @@
+import type { Attachment, ChannelInfo, ChannelSummary, Incoming, ToolSpec } from "../../src/index.ts";
+/** One graded expect item of a run. */
+export interface Check {
+    kind: "outcome" | "judge";
+    text: string;
+    pass: boolean;
+    reason: string;
+}
+/** Model tokens and their cost, added up over a run. */
+export interface Usage {
+    input: number;
+    output: number;
+    costUsd: number;
+}
+export interface OpenSession {
+    /** name: a stable key (the package name) that keeps the agent's history together; title: for people. */
+    agent: {
+        name: string;
+        title?: string;
+        tools: ToolSpec[];
+        channels?: ChannelSummary[];
+    };
+    /** Every file in the local suite; only these tests run. */
+    files: Array<{
+        path: string;
+        hash: string;
+    }>;
+    /** How many times each scenario runs. */
+    runs: number;
+    /** Acknowledge each message independently of the serial event uploads. */
+    deliveryReceipts?: boolean;
+    /** The client will retry a call when this cloud stores the result under Idempotency-Key. */
+    retries?: boolean;
+    /** The client opens a lost stream again with Last-Event-ID when this cloud resumes. */
+    resume?: boolean;
+    /** The client opens one new session for the unfinished runs when this cloud says session_gone. */
+    reopen?: boolean;
+    /** Play only these runs, numbered as given: a re-open after session_gone. Sent only to a cloud whose Opened said reopen,
+     * and only when some run finished: the cloud checks it against the suite's files it already stores. */
+    only?: RunKey[];
+}
+/** One run of a suite: a scenario's id, one of its channels, and which of the `runs` times (from 1). */
+export interface RunKey {
+    scenario: string;
+    channel: string;
+    run: number;
+}
+export interface Receipt {
+    conversationId: string;
+    messageId: string;
+    status: "taken" | "intercepted";
+}
+export interface Opened {
+    sessionId: string;
+    token: string;
+    /** Hashes the cloud does not have yet; upload these. */
+    missing: string[];
+    /** Where to watch this session's runs. */
+    dashboard: string;
+    /** The tunnel's absolute URL, where every later call goes (a hosted cloud's front door serves
+     * only the open). Absent or empty: the open's own address (a local cloud). */
+    tunnel?: string;
+    /** This cloud stores each Idempotency-Key with its result. Absent on an older cloud. */
+    idempotency?: boolean;
+    /** This cloud numbers stream commands with an SSE id, sends the ones after Last-Event-ID to a
+     * stream opened again, and holds them 2 minutes while none is attached. Absent on an older cloud. */
+    resume?: boolean;
+    /** This cloud answers session_gone for a session it lost, and plays `only` on an open. Absent on an older cloud. */
+    reopen?: boolean;
+}
+export interface UploadFile {
+    hash: string;
+    path: string;
+    content: string;
+}
+export type Command = {
+    type: "message";
+    conversationId: string;
+    messageId: string;
+    incoming: WireIncoming;
+    channel: ChannelInfo;
+    channelName?: string;
+} | {
+    type: "reaction";
+    conversationId: string;
+    emoji: string;
+    toText: string;
+} | {
+    type: "drain";
+} | {
+    type: "run";
+    run: RunSummary;
+} | {
+    type: "finished";
+    summary: SessionSummary;
+}
+/** The session stopped before it finished; the CLI exits with this error. */
+ | {
+    type: "failed";
+    error: string;
+};
+/**
+ * A person's message as it travels: a scenario's file goes by its path in the tests folder, and the
+ * agent's side reads it there, so the file never leaves the developer's machine.
+ */
+export type WireIncoming = Omit<Incoming, "attachments"> & {
+    attachments?: Array<{
+        kind: Attachment["kind"];
+        file: string;
+    }>;
+};
+export interface ToolCallRequest {
+    conversationId: string;
+    tool: string;
+    input: unknown;
+}
+export type ToolCallResult = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+export interface RunSummary {
+    runId: string;
+    scenario: string;
+    run: number;
+    channel: string;
+    /** Every check passed. */
+    passed: boolean;
+    checks: Check[];
+    /** Why the person stopped: goal met, gave up, max turns, or the agent went quiet. */
+    ended: string;
+    turns: number;
+    messagesIn: number;
+    messagesOut: number;
+    toolCalls: number;
+    /** Slowest acknowledgement of a person's message, in ms (null if one was never acknowledged). */
+    slowestAckMs: number | null;
+    /** The agent's model calls in this run, from its own events, and the models that answered them. */
+    agentUsage: Usage;
+    agentModels: string[];
+    /** The test's own model calls in this run: the person, the tool simulator and the judge. */
+    testUsage: Usage;
+    watch: string;
+    /** The first try never reached the agent, so this run is the second try. */
+    retried?: boolean;
+    /** The cloud's code when it could not play or judge the run (judge_failed, spend_cap, simulator_failed, ...).
+     * The run then says nothing about the agent, whatever `passed` and `ended` say. */
+    error?: string;
+}
+export interface SessionSummary {
+    sessionId: string;
+    suiteHash: string;
+    /** The model that played the person and the tools and judged. */
+    testModel: string;
+    runs: RunSummary[];
+    dashboard: string;
+}

package/dist/testing/src/protocol.js

@@ -0,0 +1,28 @@
+// What travels through the tunnel between an agent on a developer's machine and the test cloud.
+// Every connection is opened by the agent's side (plain HTTP), so it works behind any router.
+//
+//   POST /api/sessions                 OpenSession → Opened     start a session, learn which files to upload
+//   POST /api/files                    { files: UploadFile[] }   upload the files the cloud lacks
+//   GET  /api/sessions/:id/stream      server-sent Commands     the person's side, cloud → agent
+//        Last-Event-ID: N                                    a resume: the commands after N
+//   POST /api/sessions/:id/outbound    { conversationId, outbound } → { ok } | 409 { error }
+//   POST /api/sessions/:id/tool-calls  ToolCallRequest → ToolCallResult   held open while the tool is simulated
+//   POST /api/sessions/:id/events      { seq, events: FlowEvent[] }
+//
+// Every POST after the open sends Idempotency-Key. An older cloud ignores it. When Opened
+// says idempotency, a repeat of a key is the stored answer and the client may send it again.
+//   POST /api/sessions/:id/receipts    Receipt → { ok }
+//   POST /api/sessions/:id/drained     {} → { ok }   flush before the terminal command
+//
+// When Opened says resume, every command on the stream carries `id: N` (1, 2, 3, ... per session).
+// A stream that drops, or sits silent past the idle watch, is opened again with Last-Event-ID set
+// to the last id the client handled (0 for none); the cloud sends the commands after it, and holds
+// them for 2 minutes while no stream is attached. The client skips an id it has handled.
+//
+// When Opened says reopen, a tunnel call or the stream may answer 410 { error: "session_gone" }: the
+// cloud lost the session (its tunnel restarted). The client opens one new session with `only`, the
+// runs that have no result yet, and merges the two reports. Never more than once.
+//
+// The open goes to the cloud's front door; every later call goes to Opened.tunnel (else the same
+// address) and carries `authorization: Bearer <token>` from Opened.
+export {};

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

@@ -0,0 +1,74 @@
+/** How a `flow test` ended, one per exit status (0 passed; 1 failed, invalid; 2 errored, transport; 3 refused; 130 interrupted). */
+export type Outcome = "passed" | "failed" | "errored" | "transport" | "refused" | "interrupted" | "invalid";
+export type Verdict = "passed" | "failed" | "errored" | "not_played";
+export interface ReportError {
+    message: string;
+    /** The cloud's HTTP status, when it answered one. */
+    status: number | null;
+    /** The cloud's code for it, such as spend_cap or rate_limited. */
+    type: string | null;
+    retryAfterSeconds: number | null;
+}
+export interface ReportRun {
+    runId: string | null;
+    /** The scenario's file name without .yaml, as --only takes it. */
+    scenario: string;
+    channel: string;
+    run: number;
+    verdict: Verdict;
+    /** The cloud's code when it could not play or judge the run (judge_failed, spend_cap, ...); else null. */
+    error: string | null;
+    ended: string | null;
+    turns: number | null;
+    watch: string | null;
+    failedChecks: Array<{
+        kind: string;
+        text: string;
+        reason: string;
+    }>;
+}
+/** `flow test --json`: one document on stdout, whatever the exit. */
+export interface JsonReport {
+    version: 1;
+    outcome: Outcome;
+    exitCode: number;
+    sessionId: string | null;
+    /** The cloud's id for the agent, which `flow show` reads runs under. */
+    agent: string | null;
+    dashboard: string | null;
+    suiteHash: string | null;
+    error: ReportError | null;
+    counts: {
+        runs: number;
+        passed: number;
+        failed: number;
+        errored: number;
+        notPlayed: number;
+    };
+    costUsd: {
+        agent: number;
+        test: number;
+    };
+    runs: ReportRun[];
+}
+/** A run's verdict: errored when the cloud names an error for it or ended it run_failed, since the cloud
+ * could not play or judge it and that says nothing about the agent (a judge_failed run can end goal_met). */
+export declare function runVerdict(run: {
+    passed: boolean;
+    ended: string;
+    error?: string;
+}): Exclude<Verdict, "not_played">;
+export declare const EXIT: Record<Outcome, number>;
+/** A session that ran to its summary: failed when a run failed, errored when the cloud could not play or judge a run (or never played it). */
+export declare function finishedOutcome(runs: Array<{
+    verdict: Verdict;
+}>): Outcome;
+/** What stopped a session, or the open, as an outcome. `opened`: the session had opened. */
+export declare function stoppedOutcome(error: unknown, opened: boolean): Outcome;
+/** The error as the JSON report says it: the cloud's status, code and Retry-After when it answered. */
+export declare function reportError(error: unknown, message: string): ReportError;
+/** The connection's error code, from the error or what caused it. */
+export declare function networkCode(error: unknown): string | undefined;
+/** The agent folder's .env, or the --dotenv given; variables already set win, and no value is ever printed.
+ * Returns what is wrong when a named file cannot be read. */
+export declare function loadEnv(file: string | undefined): string | undefined;

package/dist/testing/src/report.js

@@ -0,0 +1,90 @@
+// What `flow test --json` prints, how an error that stopped a session is classified into an
+// outcome and an exit status, and the pieces `flow test` and `flow show` share.
+import { existsSync } from "node:fs";
+import { CloudEnded, isTransportFailure, PostError, SessionStopped } from "./client.js";
+/** A run's verdict: errored when the cloud names an error for it or ended it run_failed, since the cloud
+ * could not play or judge it and that says nothing about the agent (a judge_failed run can end goal_met). */
+export function runVerdict(run) {
+    if (run.error || run.ended === "run_failed")
+        return "errored";
+    return run.passed ? "passed" : "failed";
+}
+export const EXIT = { passed: 0, failed: 1, invalid: 1, errored: 2, transport: 2, refused: 3, interrupted: 130 };
+/** A session that ran to its summary: failed when a run failed, errored when the cloud could not play or judge a run (or never played it). */
+export function finishedOutcome(runs) {
+    if (runs.some((r) => r.verdict === "failed"))
+        return "failed";
+    if (runs.some((r) => r.verdict !== "passed"))
+        return "errored";
+    return "passed";
+}
+/** What stopped a session, or the open, as an outcome. `opened`: the session had opened. */
+export function stoppedOutcome(error, opened) {
+    if (error instanceof SessionStopped)
+        return "transport";
+    if (error instanceof CloudEnded)
+        return error.code === "spend_cap" || error.code === "capacity" ? "refused" : "errored";
+    const refusal = postErrorOf(error);
+    if (refusal) {
+        const why = refusal.type ?? refusal.code;
+        if (refusal.status === 503 && why === "capacity")
+            return "refused";
+        if (refusal.status >= 400 && refusal.status < 500 && why)
+            return "refused";
+        return "transport";
+    }
+    if (isTransportFailure(error) || networkCode(error))
+        return "transport";
+    // Something on this machine: the agent would not build before the open, or broke the session after it.
+    return opened ? "failed" : "invalid";
+}
+/** The error as the JSON report says it: the cloud's status, code and Retry-After when it answered. */
+export function reportError(error, message) {
+    const refusal = postErrorOf(error);
+    const type = refusal ? refusal.type ?? refusal.code ?? null : error instanceof CloudEnded ? error.code ?? null : null;
+    const retry = refusal?.retryAfterMs;
+    return { message, status: refusal?.status ?? null, type, retryAfterSeconds: retry === undefined ? null : Math.ceil(retry / 1000) };
+}
+function postErrorOf(error) {
+    let current = error;
+    for (let guard = 0; current instanceof Error && guard < 6; guard++) {
+        if (current instanceof PostError)
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+}
+/** The connection's error code, from the error or what caused it. */
+export function networkCode(error) {
+    let current = error;
+    for (let guard = 0; current instanceof Error && guard < 6; guard++) {
+        const code = current.code;
+        if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "ETIMEDOUT" || code === "ECONNRESET")
+            return code;
+        for (const inner of current instanceof AggregateError ? current.errors : []) {
+            const innerCode = networkCode(inner);
+            if (innerCode)
+                return innerCode;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/** The agent folder's .env, or the --dotenv given; variables already set win, and no value is ever printed.
+ * Returns what is wrong when a named file cannot be read. */
+export function loadEnv(file) {
+    if (file === undefined) {
+        if (existsSync(".env"))
+            process.loadEnvFile(".env");
+        return undefined;
+    }
+    if (!existsSync(file))
+        return `--dotenv ${file}: no such file.`;
+    try {
+        process.loadEnvFile(file);
+    }
+    catch (error) {
+        return `--dotenv ${file} could not be read: ${error.code ?? "unreadable"}.`;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,36 @@
+/** Where every session's results go, in the agent's folder; `flow new` git-ignores .flow/. */
+export declare const LAST_SESSION: string;
+/** The last session's file in dir: LAST_SESSION, else, before a run has written it, the one from before the rename (.chinwag/). */
+export declare function lastSessionIn(dir: string): string;
+/** .flow/last-session.json: what each run ended as, for `--failed`, `flow show` and coding agents. */
+export interface LastSession {
+    sessionId: string;
+    /** The cloud's id for the agent, from the open (an older cloud names none). */
+    agent?: string;
+    dashboard: string;
+    suiteHash: string;
+    /** When the session ended, as an ISO time. */
+    endedAt: string;
+    ended: "finished" | "stopped" | "interrupted";
+    /** The scenarios this session was limited to (--only, --failed); null when it ran the whole suite. */
+    only: string[] | null;
+    runs: Array<{
+        /** The scenario's file name without .yaml, as --only takes it. */
+        scenario: string;
+        channel: string;
+        run: number;
+        /** The cloud's id for the run, for `flow show`; null when it was not played. */
+        runId?: string | null;
+        verdict: "passed" | "failed" | "errored" | "not_played";
+        /** The checks as the test file says them, with the judge's reason. The file is local and
+         * git-ignored, and the suite is synthetic by attestation; the messages themselves are never kept. */
+        failedChecks: Array<{
+            kind: string;
+            text: string;
+            reason?: string;
+        }>;
+    }>;
+}
+export declare const SHOW_LINE = "  flow show <run-id|last> [--json]\n                            Print one run's record from the test cloud: its checks with the\n                            judge's reasons, the transcript and the tool calls (flow show --help)";
+/** `flow show`: returns the exit status. */
+export declare function showCli(args: string[]): Promise<number>;