@flow-engineer/flow 0.0.1 → 0.2.0

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

@@ -0,0 +1,115 @@
+import { type Agent, type EventSink, type Tool } from "../../src/index.ts";
+import type { Opened, RunSummary, SessionSummary } from "./protocol.ts";
+import { type SuiteFile } from "./suite.ts";
+export interface ConnectOptions {
+    /** The cloud's address, such as http://127.0.0.1:8900. */
+    cloud: string;
+    /** A stable key for the agent (its package name), which keeps its history together. */
+    name: string;
+    /** The agent's name for people, shown in the dashboard. */
+    title?: string;
+    /** The agent's real tools: only their names, descriptions and inputs are used. */
+    tools: Tool[];
+    /** Builds the agent with the tools and events it is given: a Flow Framework Agent, or anything that answers like one (http-agent.ts). */
+    build: (options: {
+        tools: Tool[];
+        events: EventSink[];
+    }) => AgentUnderTest;
+    files: SuiteFile[];
+    /** The tests folder: files a scenario attaches are read from here, and never leave this machine. */
+    testsDir?: string;
+    runs?: number;
+    log?: (line: string) => void;
+    /** Headers for the open only (cloudHeaders: the CI key and the attestation); never sent to the tunnel. */
+    openHeaders?: Record<string, string>;
+    /** Called as each run finishes, before the session's summary. An older cloud sends none. */
+    onRun?: (run: RunSummary) => void;
+    /** Called once the session has opened, with its dashboard link, its id, and the cloud's id for the agent (a hosted cloud answers one). */
+    onDashboard?: (url: string, sessionId: string, agent?: string) => void;
+    /** How long one POST waits before the size allowance. Default 30s, plus 1s per 100KB of body. A tool call waits {@link CLOUD_MODEL_BUDGET_MS} plus the simulator's latency, unless this is set. */
+    postTimeoutMs?: number;
+    /** How long the stream may sit with no bytes, including the cloud's 15s ping. Default 45s. */
+    streamIdleMs?: number;
+    /** How long one call keeps trying after its first failure. Default 30s. */
+    retryBudgetMs?: number;
+    /** How long a lost stream keeps trying to resume, on a cloud that resumes (Opened.resume). Default 2 minutes, as long as the cloud holds its commands. */
+    resumeWindowMs?: number;
+    /** How often a resumable stream is replaced, before the tunnel's one-hour request cap. Default 50 minutes. */
+    streamRefreshMs?: number;
+    /** The longest Retry-After a busy cloud's refused open is sent again after, once. Default 60s. */
+    openRetryCapMs?: number;
+    /** Also log slow event uploads. */
+    verbose?: boolean;
+}
+/** The session opened, then the cloud ended it with a `failed` command. `code` is the reason's leading
+ * code (`capacity: ...` gives capacity), when it starts with one. */
+export declare class CloudEnded extends Error {
+    readonly code?: string;
+    constructor(error: string);
+}
+/** The tunnel, the stream, or the connection failed after the session opened. `runs` are the ones already received. The CLI prints them and exits 2. */
+export declare class SessionStopped extends Error {
+    readonly runs: RunSummary[];
+    readonly dashboard: string;
+    constructor(reason: string, runs: RunSummary[], dashboard: string);
+}
+/** What runInCloud answers. When the cloud lost the session and a second one played the runs it had not finished, `runs` holds both sessions' runs and `lost` names the first. */
+export type CloudSummary = SessionSummary & {
+    lost?: {
+        sessionId: string;
+        dashboard: string;
+    };
+};
+/** A POST that sat until its own deadline. It fails that one call. Only a cloud that stores keys sends it again. The session abort is not one of these. */
+export declare class TimeoutError extends Error {
+    constructor();
+}
+/** The stream stopped carrying bytes: the idle watch fired, or the cloud closed it before finished. */
+export declare class StreamLost extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** How long one call keeps trying after its first failure. The first try's own wait does not count, so a timed-out try is still sent again. */
+export declare const RETRY_BUDGET_MS = 30000;
+/** The cloud abandons one model attempt at 90s and tries a timeout once more, then this POST has its 30s. */
+export declare const CLOUD_MODEL_BUDGET_MS: number;
+/** How long a tool call may take: the longest latency its suite file declares, plus {@link CLOUD_MODEL_BUDGET_MS} (210s).
+ * A tool with no file gets the simulator's own cap (60s) plus that 210s.
+ *
+ * The cloud asks its model before the declared latency, and the model's own time counts toward it.
+ * 210s is two 90s attempts plus the 30s POST budget, so a stuck model can finish before this POST gives up.
+ * When it runs out, the agent sees an error while the cloud may still record the call in the world log once the model returns. */
+export declare function toolTimeoutMs(files: SuiteFile[], tool: string, budgetMs?: number): number;
+/** The base budget plus 1s per 100KB, so a 5MB event batch or file upload is not cut off at 30s. */
+export declare function postBudgetMs(baseMs: number, bytes: number): number;
+/** What the cloud plays: a Flow Framework Agent's channels, messages in and reactions. */
+export type AgentUnderTest = Pick<Agent, "channels" | "receive" | "reacted"> & Partial<Pick<Agent, "hasProfile">>;
+export interface CloudAccess {
+    /** The cloud's front door, as given to --cloud. */
+    cloud: string;
+    /** The agent's CI key (FLOW_FRAMEWORK_CLOUD_KEY). */
+    ciKey?: string;
+    /** Whoever runs the tests attests that the test files hold no real people's data. */
+    synthetic: boolean;
+    agentVersion?: string;
+    ref?: string;
+    environment?: string;
+}
+/** The open's headers. A cloud off this machine needs the CI key and the synthetic attestation;
+ * a local one needs neither, and gets them when they are given. */
+export declare function cloudHeaders(access: CloudAccess): Record<string, string>;
+/** Where the session is played: Opened.tunnel when the cloud answers one, else the open's own address. */
+export declare function tunnelBase(cloud: string, opened: Pick<Opened, "tunnel">): string;
+/** Plays the suite in the cloud. If the cloud loses the session (session_gone, on a cloud whose open said
+ * reopen), one new session plays only the runs that have no result yet, and the two reports are merged. */
+export declare function runInCloud(options: ConnectOptions): Promise<CloudSummary>;
+/** The cloud answered a call with a status that is not 2xx. `code` is a JSON `error` string (the tunnel's
+ * refusals, which retries go by); `type` is a JSON `error` object's type (a hosted cloud's front door). */
+export declare class PostError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly type?: string;
+    readonly retryAfterMs?: number;
+    constructor(url: string, status: number, text: string, retryAfterMs?: number);
+}
+/** The tunnel, the stream, or the connection, as opposed to a refusal the cloud wrote as JSON. */
+export declare function isTransportFailure(error: unknown): boolean;