@kici-dev/compiler 0.0.0 → 0.1.2

package/dist/remote/history.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Local run history manager.
+ *
+ * Persists test run history in ~/.kici/history/runs.json so developers
+ * can review past runs (kici test --history) and inspect specific runs
+ * (kici status <run-id>).
+ */
+/** Status of a test run */
+type RunStatus = 'queued' | 'running' | 'success' | 'failed' | 'cancelled';
+/** A single run history entry */
+export interface HistoryEntry {
+    /** Unique run identifier */
+    runId: string;
+    /** Fixture that was run */
+    fixtureId: string;
+    /** Current status of the run */
+    status: RunStatus;
+    /** ISO timestamp when the run started */
+    startedAt: string;
+    /** ISO timestamp when the run completed (if finished) */
+    completedAt?: string;
+    /** Total duration in milliseconds (if finished) */
+    durationMs?: number;
+    /** Orchestrator endpoint used */
+    endpoint: string;
+    /** Job-level status breakdown */
+    jobs?: Array<{
+        name: string;
+        status: string;
+        durationMs?: number;
+    }>;
+}
+/** Filter criteria for querying history entries */
+interface HistoryFilter {
+    /** Exact status match */
+    status?: string;
+    /** Fixture glob pattern (via picomatch) */
+    fixture?: string;
+    /** Maximum number of entries to return */
+    limit?: number;
+}
+/**
+ * Manages local run history stored in ~/.kici/history/runs.json.
+ *
+ * Entries are capped at 200 (oldest removed first when exceeded).
+ * The history file is created lazily on first write.
+ */
+export declare class RunHistory {
+    private readonly historyDir;
+    private readonly historyFile;
+    private entries;
+    constructor(historyDir?: string);
+    /**
+     * Add a new entry to the history.
+     * Creates the history file and directory if they don't exist.
+     * Caps history at MAX_ENTRIES by removing the oldest entries.
+     */
+    addEntry(entry: HistoryEntry): Promise<void>;
+    /**
+     * Update an existing entry by runId.
+     * Merges the provided updates into the existing entry.
+     * No-op if the runId is not found.
+     */
+    updateEntry(runId: string, updates: Partial<HistoryEntry>): Promise<void>;
+    /**
+     * Get entries with optional filtering.
+     * Returns entries in most-recent-first order.
+     */
+    getEntries(filter?: HistoryFilter): HistoryEntry[];
+    /**
+     * Get a single entry by runId.
+     */
+    getEntry(runId: string): HistoryEntry | undefined;
+    /**
+     * Format entries as a table string for terminal display.
+     *
+     * Columns: Run ID | Fixture | Status | Duration | Started
+     * Status is color-coded, Started uses relative time.
+     */
+    formatTable(entries: HistoryEntry[]): string;
+    /**
+     * Load entries from disk. Caches in memory for subsequent reads.
+     */
+    load(): Promise<HistoryEntry[]>;
+    /**
+     * Write entries to disk.
+     */
+    private save;
+}
+export {};
+//# sourceMappingURL=history.d.ts.map

package/dist/remote/history.js

@@ -0,0 +1,146 @@
+import "../chunk-gOLHoazu.js";
+import { getConfigDir } from "./config.js";
+import { formatRelativeTime } from "../format.js";
+import pc from "picocolors";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { formatDuration } from "@kici-dev/shared";
+import picomatch from "picomatch";
+//#region src/remote/history.ts
+/**
+* Local run history manager.
+*
+* Persists test run history in ~/.kici/history/runs.json so developers
+* can review past runs (kici test --history) and inspect specific runs
+* (kici status <run-id>).
+*/
+/** Maximum number of entries to keep in history */
+const MAX_ENTRIES = 200;
+/**
+* Manages local run history stored in ~/.kici/history/runs.json.
+*
+* Entries are capped at 200 (oldest removed first when exceeded).
+* The history file is created lazily on first write.
+*/
+var RunHistory = class {
+	historyDir;
+	historyFile;
+	entries = null;
+	constructor(historyDir) {
+		this.historyDir = historyDir ?? path.join(getConfigDir(), "history");
+		this.historyFile = path.join(this.historyDir, "runs.json");
+	}
+	/**
+	* Add a new entry to the history.
+	* Creates the history file and directory if they don't exist.
+	* Caps history at MAX_ENTRIES by removing the oldest entries.
+	*/
+	async addEntry(entry) {
+		const entries = await this.load();
+		entries.push(entry);
+		while (entries.length > MAX_ENTRIES) entries.shift();
+		await this.save(entries);
+	}
+	/**
+	* Update an existing entry by runId.
+	* Merges the provided updates into the existing entry.
+	* No-op if the runId is not found.
+	*/
+	async updateEntry(runId, updates) {
+		const entries = await this.load();
+		const index = entries.findIndex((e) => e.runId === runId);
+		if (index === -1) return;
+		entries[index] = {
+			...entries[index],
+			...updates
+		};
+		await this.save(entries);
+	}
+	/**
+	* Get entries with optional filtering.
+	* Returns entries in most-recent-first order.
+	*/
+	getEntries(filter) {
+		const entries = this.entries ? [...this.entries] : [];
+		entries.reverse();
+		let filtered = entries;
+		if (filter?.status) filtered = filtered.filter((e) => e.status === filter.status);
+		if (filter?.fixture) {
+			const matcher = picomatch(filter.fixture);
+			filtered = filtered.filter((e) => matcher(e.fixtureId));
+		}
+		if (filter?.limit && filter.limit > 0) filtered = filtered.slice(0, filter.limit);
+		return filtered;
+	}
+	/**
+	* Get a single entry by runId.
+	*/
+	getEntry(runId) {
+		if (!this.entries) return void 0;
+		return this.entries.find((e) => e.runId === runId);
+	}
+	/**
+	* Format entries as a table string for terminal display.
+	*
+	* Columns: Run ID | Fixture | Status | Duration | Started
+	* Status is color-coded, Started uses relative time.
+	*/
+	formatTable(entries) {
+		if (entries.length === 0) return pc.gray("No run history found.");
+		const idWidth = Math.max(10, ...entries.map((e) => e.runId.length)) + 2;
+		const fixtureWidth = Math.max(10, ...entries.map((e) => e.fixtureId.length)) + 2;
+		const lines = [];
+		lines.push(`${"Run ID".padEnd(idWidth)}${"Fixture".padEnd(fixtureWidth)}${"Status".padEnd(12)}${"Duration".padEnd(12)}Started`);
+		lines.push(`${"".padEnd(idWidth - 1, "-")} ${"".padEnd(fixtureWidth - 1, "-")} ${"".padEnd(10, "-")} ${"".padEnd(10, "-")} ${"".padEnd(15, "-")}`);
+		for (const entry of entries) {
+			const id = entry.runId.padEnd(idWidth);
+			const fixture = entry.fixtureId.padEnd(fixtureWidth);
+			const status = formatStatus(entry.status).padEnd(12);
+			const duration = entry.durationMs ? formatDuration(entry.durationMs).padEnd(12) : "-".padEnd(12);
+			const started = formatRelativeTime(entry.startedAt);
+			lines.push(`${id}${fixture}${status}${duration}${started}`);
+		}
+		return lines.join("\n");
+	}
+	/**
+	* Load entries from disk. Caches in memory for subsequent reads.
+	*/
+	async load() {
+		if (this.entries !== null) return this.entries;
+		try {
+			const content = await fs.readFile(this.historyFile, "utf-8");
+			this.entries = JSON.parse(content);
+			return this.entries;
+		} catch (err) {
+			if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+				this.entries = [];
+				return this.entries;
+			}
+			throw err;
+		}
+	}
+	/**
+	* Write entries to disk.
+	*/
+	async save(entries) {
+		await fs.mkdir(this.historyDir, { recursive: true });
+		await fs.writeFile(this.historyFile, JSON.stringify(entries, null, 2) + "\n");
+		this.entries = entries;
+	}
+};
+/**
+* Format a run status with appropriate color and symbol.
+*/
+function formatStatus(status) {
+	switch (status) {
+		case "success": return pc.green("pass");
+		case "failed": return pc.red("fail");
+		case "cancelled": return pc.yellow("cancel");
+		case "running": return pc.blue("running");
+		case "queued": return pc.gray("queued");
+	}
+}
+//#endregion
+export { RunHistory };
+
+//# sourceMappingURL=history.js.map

package/dist/remote/oauth.d.ts

@@ -0,0 +1,65 @@
+/** Options for the PKCE authorization code flow. */
+interface PkceFlowOptions {
+    /** OIDC issuer URL (e.g., https://auth.your-domain.example.com) */
+    issuer: string;
+    /** OAuth client ID for the CLI application */
+    clientId: string;
+    /** OIDC project ID (adds audience scope for JWT access tokens) */
+    projectId?: string;
+}
+/** Options for the RFC 8628 device authorization flow. */
+interface DeviceFlowOptions {
+    /** OIDC issuer URL */
+    issuer: string;
+    /** OAuth client ID for the CLI application */
+    clientId: string;
+    /** OIDC project ID (adds audience scope for JWT access tokens) */
+    projectId?: string;
+}
+/** Options for exchanging an OIDC token for a PAT. */
+interface ExchangeTokenOptions {
+    /** Platform API base URL */
+    platformUrl: string;
+    /** OIDC access token */
+    accessToken: string;
+    /** Machine hostname for PAT naming */
+    machineName: string;
+}
+/** Response from the PAT exchange endpoint. */
+interface ExchangeTokenResult {
+    /** PAT identifier */
+    id: string;
+    /** Raw PAT value (kici_pat_...) */
+    token: string;
+    /** ISO 8601 expiry timestamp */
+    expiresAt: string;
+}
+/**
+ * PKCE authorization code flow with localhost callback.
+ *
+ * Spins up a temporary HTTP server on a random port, opens the browser
+ * to the ZITADEL authorization endpoint, captures the callback with the
+ * authorization code, and exchanges it for tokens.
+ *
+ * @returns OIDC access token
+ */
+export declare function pkceFlow(opts: PkceFlowOptions): Promise<string>;
+/**
+ * RFC 8628 device authorization flow.
+ *
+ * Requests a device code from ZITADEL, displays the user code and
+ * verification URI, then polls the token endpoint until the user
+ * authorizes the device or the code expires.
+ *
+ * @returns OIDC access token
+ */
+export declare function deviceFlow(opts: DeviceFlowOptions): Promise<string>;
+/**
+ * Exchange an OIDC access token for a personal access token (PAT).
+ *
+ * POSTs to the Platform /api/v1/cli/exchange-token endpoint with the
+ * OIDC token as Bearer auth. Returns the generated PAT details.
+ */
+export declare function exchangeTokenForPat(opts: ExchangeTokenOptions): Promise<ExchangeTokenResult>;
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/remote/oauth.js

@@ -0,0 +1,302 @@
+import "../chunk-gOLHoazu.js";
+import pc from "picocolors";
+import { exec } from "node:child_process";
+import { toErrorMessage } from "@kici-dev/shared";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import open from "open";
+//#region src/remote/oauth.ts
+/**
+* Wrap a fetch call so that transport errors (DNS failure, connection refused,
+* TLS handshake failure) surface with the URL that failed and a hint about
+* which env var the user should check, instead of Node's bare "fetch failed".
+*/
+async function fetchOrThrow(url, init, kind) {
+	try {
+		return await fetch(url, init);
+	} catch (err) {
+		const envHint = kind === "Platform" ? "KICI_PLATFORM_URL" : "KICI_OIDC_ISSUER";
+		throw new Error(`Could not reach ${kind} at ${url} (${toErrorMessage(err)}). Check ${envHint}.`);
+	}
+}
+/**
+* Generate a PKCE code verifier and challenge.
+*
+* Verifier: 32 random bytes, base64url encoded.
+* Challenge: SHA-256 of verifier, base64url encoded.
+*/
+function generatePkceChallenge() {
+	const verifier = randomBytes(32).toString("base64url");
+	return {
+		verifier,
+		challenge: createHash("sha256").update(verifier).digest("base64url")
+	};
+}
+/** HTML page served after successful PKCE callback. */
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>KiCI - Login successful</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      margin: 0;
+      background: #0f1117;
+      color: #e1e1e6;
+    }
+    .card {
+      text-align: center;
+      padding: 3rem 2rem;
+      background: #1a1b23;
+      border-radius: 12px;
+      border: 1px solid #2d2e3a;
+      max-width: 420px;
+    }
+    .logo { font-size: 2.5rem; font-weight: 700; margin-bottom: 1rem; }
+    .logo span { color: #4c6ef5; }
+    .check { font-size: 3rem; margin-bottom: 1rem; }
+    h1 { font-size: 1.5rem; margin: 0 0 0.5rem; }
+    p { color: #8b8c99; margin: 0.5rem 0; }
+    .hint { font-size: 0.875rem; color: #6b6c7a; margin-top: 1.5rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="logo">Ki<span>CI</span></div>
+    <div class="check">&#10003;</div>
+    <h1>Login success!</h1>
+    <p>You can close this tab and return to your terminal.</p>
+    <p class="hint">Your CLI session has been authenticated.</p>
+  </div>
+</body>
+</html>`;
+/**
+* PKCE authorization code flow with localhost callback.
+*
+* Spins up a temporary HTTP server on a random port, opens the browser
+* to the ZITADEL authorization endpoint, captures the callback with the
+* authorization code, and exchanges it for tokens.
+*
+* @returns OIDC access token
+*/
+async function pkceFlow(opts) {
+	const { issuer, clientId, projectId } = opts;
+	const { verifier, challenge } = generatePkceChallenge();
+	const state = randomBytes(16).toString("hex");
+	let listenPort = 0;
+	const callbackPortEnv = process.env.KICI_CALLBACK_PORT;
+	if (callbackPortEnv) {
+		const parsed = parseInt(callbackPortEnv, 10);
+		if (isNaN(parsed) || parsed < 0) throw new Error(`KICI_CALLBACK_PORT must be a valid non-negative integer, got: "${callbackPortEnv}"`);
+		listenPort = parsed;
+	}
+	const TIMEOUT_MS = 300 * 1e3;
+	return new Promise((resolve, reject) => {
+		let timer;
+		const server = createServer(async (req, res) => {
+			const url = new URL(req.url, `http://127.0.0.1`);
+			if (url.pathname !== "/callback") {
+				res.writeHead(404);
+				res.end("Not found");
+				return;
+			}
+			const code = url.searchParams.get("code");
+			const returnedState = url.searchParams.get("state");
+			const error = url.searchParams.get("error");
+			if (error) {
+				const description = url.searchParams.get("error_description") || error;
+				res.writeHead(400, { "Content-Type": "text/plain" });
+				res.end(`Authentication error: ${description}`);
+				cleanup();
+				reject(/* @__PURE__ */ new Error(`Authentication error: ${description}`));
+				return;
+			}
+			if (returnedState !== state) {
+				res.writeHead(400, { "Content-Type": "text/plain" });
+				res.end("State mismatch - possible CSRF attack");
+				cleanup();
+				reject(/* @__PURE__ */ new Error("State mismatch - possible CSRF attack"));
+				return;
+			}
+			if (!code) {
+				res.writeHead(400, { "Content-Type": "text/plain" });
+				res.end("Missing authorization code");
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Missing authorization code in callback"));
+				return;
+			}
+			res.writeHead(200, { "Content-Type": "text/html" });
+			res.end(SUCCESS_HTML);
+			const port = server.address().port;
+			try {
+				const tokenRes = await fetchOrThrow(`${issuer}/oauth/v2/token`, {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: new URLSearchParams({
+						grant_type: "authorization_code",
+						client_id: clientId,
+						code,
+						redirect_uri: `http://127.0.0.1:${port}/callback`,
+						code_verifier: verifier
+					})
+				}, "Zitadel");
+				if (!tokenRes.ok) {
+					const errorBody = await tokenRes.text();
+					cleanup();
+					reject(/* @__PURE__ */ new Error(`Token exchange failed: ${errorBody}`));
+					return;
+				}
+				const tokenData = await tokenRes.json();
+				cleanup();
+				resolve(tokenData.access_token);
+			} catch (err) {
+				cleanup();
+				reject(err);
+			}
+		});
+		function cleanup() {
+			if (timer) clearTimeout(timer);
+			if (server.listening) server.close();
+		}
+		server.listen(listenPort, "127.0.0.1", () => {
+			const actualPort = server.address().port;
+			const redirectUri = `http://127.0.0.1:${actualPort}/callback`;
+			const authUrl = new URL(`${issuer}/oauth/v2/authorize`);
+			authUrl.searchParams.set("client_id", clientId);
+			authUrl.searchParams.set("redirect_uri", redirectUri);
+			authUrl.searchParams.set("response_type", "code");
+			const scopes = [
+				"openid",
+				"profile",
+				"email",
+				"offline_access"
+			];
+			if (projectId) scopes.push(`urn:zitadel:iam:org:project:id:${projectId}:aud`);
+			authUrl.searchParams.set("scope", scopes.join(" "));
+			authUrl.searchParams.set("code_challenge", challenge);
+			authUrl.searchParams.set("code_challenge_method", "S256");
+			authUrl.searchParams.set("state", state);
+			const browserCmd = process.env.KICI_BROWSER_CMD;
+			if (browserCmd === "none") {
+				console.log(`KICI_AUTH_URL=${authUrl.toString()}`);
+				console.log(pc.cyan(`  Waiting for browser callback on port ${actualPort}...`));
+			} else if (browserCmd) exec(browserCmd.replace("{url}", authUrl.toString()), (err) => {
+				if (err) console.log(pc.yellow(`  Custom browser command failed: ${err.message}\n  Please visit:\n  ${authUrl.toString()}`));
+			});
+			else {
+				console.log(pc.cyan("  Opening browser for authentication..."));
+				open(authUrl.toString()).catch(() => {
+					console.log(pc.yellow(`  Could not open browser automatically. Please visit:\n  ${authUrl.toString()}`));
+				});
+			}
+		});
+		timer = setTimeout(() => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("Authentication timed out after 5 minutes. Please try again with `kici login`."));
+		}, TIMEOUT_MS);
+	});
+}
+/** Sleep helper for device flow polling. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* RFC 8628 device authorization flow.
+*
+* Requests a device code from ZITADEL, displays the user code and
+* verification URI, then polls the token endpoint until the user
+* authorizes the device or the code expires.
+*
+* @returns OIDC access token
+*/
+async function deviceFlow(opts) {
+	const { issuer, clientId, projectId } = opts;
+	const scopes = [
+		"openid",
+		"profile",
+		"email",
+		"offline_access"
+	];
+	if (projectId) scopes.push(`urn:zitadel:iam:org:project:id:${projectId}:aud`);
+	const deviceAuthRes = await fetchOrThrow(`${issuer}/oauth/v2/device_authorization`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: clientId,
+			scope: scopes.join(" ")
+		})
+	}, "Zitadel");
+	if (!deviceAuthRes.ok) {
+		const errorBody = await deviceAuthRes.text();
+		throw new Error(`Device authorization request failed: ${errorBody}`);
+	}
+	const deviceAuth = await deviceAuthRes.json();
+	console.log();
+	console.log(pc.bold("  Device authorization"));
+	if (deviceAuth.verification_uri_complete) {
+		console.log(`  Open ${pc.cyan(deviceAuth.verification_uri_complete)}`);
+		console.log(pc.gray("  The code is pre-filled; approve on the Zitadel screen."));
+		console.log(pc.gray(`  Enter code: ${pc.bold(pc.yellow(deviceAuth.user_code))} (if prompted)`));
+	} else {
+		console.log(`  Open ${pc.cyan(deviceAuth.verification_uri)}`);
+		console.log(`  Enter code: ${pc.bold(pc.yellow(deviceAuth.user_code))}`);
+	}
+	console.log(pc.gray(`  Code expires in ${Math.floor(deviceAuth.expires_in / 60)} minutes`));
+	console.log();
+	let intervalMs = (deviceAuth.interval ?? 5) * 1e3;
+	while (true) {
+		await sleep(intervalMs);
+		const tokenRes = await fetchOrThrow(`${issuer}/oauth/v2/token`, {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				client_id: clientId,
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				device_code: deviceAuth.device_code
+			})
+		}, "Zitadel");
+		if (tokenRes.ok) return (await tokenRes.json()).access_token;
+		const errorData = await tokenRes.json();
+		switch (errorData.error) {
+			case "authorization_pending": continue;
+			case "slow_down":
+				intervalMs += 5e3;
+				continue;
+			case "expired_token": throw new Error("Device code expired. Please run `kici login` again to restart authentication.");
+			case "access_denied": throw new Error(errorData.error_description || "Access denied by user");
+			default: throw new Error(errorData.error_description || `Device flow error: ${errorData.error}`);
+		}
+	}
+}
+/**
+* Exchange an OIDC access token for a personal access token (PAT).
+*
+* POSTs to the Platform /api/v1/cli/exchange-token endpoint with the
+* OIDC token as Bearer auth. Returns the generated PAT details.
+*/
+async function exchangeTokenForPat(opts) {
+	const { platformUrl, accessToken, machineName } = opts;
+	const res = await fetchOrThrow(`${platformUrl}/api/v1/cli/exchange-token`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ machineName })
+	}, "Platform");
+	if (!res.ok) {
+		const errorBody = await res.text();
+		throw new Error(`Token exchange failed (${res.status}): ${errorBody}`);
+	}
+	return await res.json();
+}
+//#endregion
+export { deviceFlow, exchangeTokenForPat, pkceFlow };
+
+//# sourceMappingURL=oauth.js.map

package/dist/remote/observer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * WebSocket observer client for real-time run streaming.
+ *
+ * Connects to the orchestrator's observer WS endpoint, subscribes to a
+ * specific run, and relays real-time events (logs, step changes, status
+ * updates, completion) to registered callbacks.
+ *
+ * Features:
+ * - Auto-reconnect with lastSeenSequence for backfill (up to 5 attempts)
+ * - Promise-based waitForCompletion()
+ * - Clean disconnect
+ */
+import type { ObserveLog, ObserveStep, ObserveStatus, ObserveComplete } from '@kici-dev/engine';
+/** Configuration for ObserverClient. */
+interface ObserverClientConfig {
+    /** WebSocket URL for the observer endpoint. */
+    observeUrl: string;
+    /** Authentication token. */
+    token: string;
+    /** Run ID to observe. */
+    runId: string;
+    /** Callback for log messages. */
+    onLog: (msg: ObserveLog & {
+        sequence: number;
+    }) => void;
+    /** Callback for step lifecycle changes. */
+    onStep: (msg: ObserveStep & {
+        sequence: number;
+    }) => void;
+    /** Callback for status changes. */
+    onStatus: (msg: ObserveStatus & {
+        sequence: number;
+    }) => void;
+    /** Callback for run completion. */
+    onComplete: (msg: ObserveComplete & {
+        sequence: number;
+    }) => void;
+    /** Callback for errors (WS errors or auth failures). */
+    onError: (err: Error) => void;
+    /** Maximum reconnection attempts. Default: 5. */
+    maxReconnectAttempts?: number;
+    /** Reconnection delay in ms. Default: 1000. */
+    reconnectDelayMs?: number;
+}
+export declare class ObserverClient {
+    private ws;
+    private lastSeenSequence;
+    private reconnectAttempts;
+    private intentionalDisconnect;
+    private initialConnectCompleted;
+    private reconnectTimer;
+    private completionResolve;
+    private completionReject;
+    private completionResult;
+    private readonly config;
+    constructor(config: ObserverClientConfig);
+    /**
+     * Connect to the observer endpoint and send the subscribe message.
+     * Resolves when the WS connection is open and subscribe is sent.
+     */
+    connect(): Promise<void>;
+    /**
+     * Returns a promise that resolves when the run completes.
+     * If the run already completed (from a prior observe.complete),
+     * resolves immediately.
+     */
+    waitForCompletion(): Promise<ObserveComplete & {
+        sequence: number;
+    }>;
+    /**
+     * Gracefully disconnect from the observer endpoint.
+     */
+    disconnect(): void;
+    /** Current lastSeenSequence (for testing). */
+    getLastSeenSequence(): number;
+    private doConnect;
+    private handleMessage;
+    private scheduleReconnect;
+}
+export {};
+//# sourceMappingURL=observer.d.ts.map