webflow-mcp 0.3.0

package/dist/src/shared/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class WebFlowError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare function toErrorMessage(error: unknown): string;

package/dist/src/shared/errors.js

@@ -0,0 +1,16 @@
+export class WebFlowError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'WebFlowError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return typeof error === 'string' ? error : 'Unknown error';
+}

package/dist/src/shared/fs.d.ts

@@ -0,0 +1,5 @@
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function ensureDir(path: string): Promise<void>;
+export declare function readJsonFile<T>(filePath: string): Promise<T>;
+export declare function writeJsonFile(filePath: string, value: unknown): Promise<void>;
+export declare function copyDir(source: string, target: string): Promise<void>;

package/dist/src/shared/fs.js

@@ -0,0 +1,23 @@
+import { cp, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureDir(path) {
+    await mkdir(path, { recursive: true });
+}
+export async function readJsonFile(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+}
+export async function writeJsonFile(filePath, value) {
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+export async function copyDir(source, target) {
+    await cp(source, target, { recursive: true, errorOnExist: false });
+}

package/dist/src/shared/paths.d.ts

@@ -0,0 +1,112 @@
+export declare const MIN_NODE_MAJOR = 20;
+export declare const WORKFLOW_DIRNAME = ".webflow";
+/** Env var to override where login sessions (Chrome profiles) are stored. */
+export declare const PROFILES_DIR_ENV = "WEBFLOW_PROFILES_DIR";
+/** Env var to override the workspace root that holds .webflow/flows (Model B cross-repo). */
+export declare const FLOWS_DIR_ENV = "WEBFLOW_FLOWS_DIR";
+/** Env var to override where the global webflow-config.json (browser visibility, etc.) lives. */
+export declare const CONFIG_PATH_ENV = "WEBFLOW_CONFIG_PATH";
+/** Env var to override where the local repertoire.json (saved flows) lives. */
+export declare const REPERTOIRE_PATH_ENV = "WEBFLOW_REPERTOIRE_PATH";
+/** Env var to override persistent provider cooldown state. */
+export declare const ANTIBLOCK_DIR_ENV = "WEBFLOW_ANTIBLOCK_DIR";
+/** Env var to override where the persisted relay login (~/.webflow/credentials.json) lives. */
+export declare const CREDENTIALS_PATH_ENV = "WEBFLOW_CREDENTIALS_PATH";
+/** Env var to override the persistent device identity used during worker pairing. */
+export declare const DEVICE_IDENTITY_PATH_ENV = "WEBFLOW_DEVICE_IDENTITY_PATH";
+/** Env vars for worker-local remote-flow trust decisions. */
+export declare const FLOW_APPROVALS_PATH_ENV = "WEBFLOW_FLOW_APPROVALS_PATH";
+export declare const FLOW_PENDING_APPROVALS_PATH_ENV = "WEBFLOW_FLOW_PENDING_APPROVALS_PATH";
+export declare const FLOW_RELEASE_STATE_PATH_ENV = "WEBFLOW_FLOW_RELEASE_STATE_PATH";
+/** Independent MCP-client credentials used only by the local unified gateway. */
+export declare const RELAY_MCP_URL_ENV = "WEBFLOW_RELAY_MCP_URL";
+export declare const RELAY_MCP_TOKEN_ENV = "WEBFLOW_RELAY_MCP_TOKEN";
+export interface WorkspacePaths {
+    projectRoot: string;
+    workspaceRoot: string;
+    flowsDir: string;
+    skillsDir: string;
+    /**
+     * Where Chrome login sessions live. Global by default (shared across repos) so
+     * you log in once and every workspace reuses the session. Per-repo state such as
+     * downloads stays under the workspace; only sessions are global.
+     */
+    profilesDir: string;
+    downloadsDir: string;
+    cacheDir: string;
+}
+/**
+ * Resolve the global profiles (login session) root, decoupled from any single
+ * repository. Honors WEBFLOW_PROFILES_DIR, otherwise defaults to ~/.webflow/profiles.
+ */
+export declare function getProfilesRoot(): string;
+/**
+ * Resolve the global webflow-config.json path (browser visibility preferences, etc.),
+ * decoupled from any single repository — same rationale as getProfilesRoot(): the person
+ * running the worker has one set of preferences, not one per project. Honors
+ * WEBFLOW_CONFIG_PATH, otherwise defaults to ~/.webflow/config.json.
+ */
+export declare function getConfigPath(): string;
+/**
+ * Resolve the global repertoire.json path (flows saved locally so the worker can expose
+ * them as direct tools without re-searching the catalog). Honors WEBFLOW_REPERTOIRE_PATH,
+ * otherwise defaults to ~/.webflow/repertoire.json.
+ */
+export declare function getRepertoirePath(): string;
+export declare function getAntiBlockDir(): string;
+/**
+ * Resolve the persisted worker-pairing path (`webflow login`'s relay URL + secret).
+ * Deliberately a SEPARATE file from config.json: that file is read wholesale
+ * and forwarded verbatim to MCP clients by the get_config tool (tool-registry.ts /
+ * mcp-endpoint.ts), so a worker secret must never live there. Honors
+ * WEBFLOW_CREDENTIALS_PATH, otherwise defaults to ~/.webflow/credentials.json.
+ */
+export declare function getCredentialsPath(): string;
+export declare function getDeviceIdentityPath(): string;
+export declare function getFlowApprovalsPath(): string;
+export declare function getFlowPendingApprovalsPath(): string;
+export declare function getFlowReleaseStatePath(): string;
+/** Env var to override where the background worker's PID file lives (src/worker/lifecycle.ts). */
+export declare const WORKER_PID_PATH_ENV = "WEBFLOW_WORKER_PID_PATH";
+/**
+ * Tracks the detached worker process started by the start_worker MCP tool
+ * (src/worker/lifecycle.ts), so stop_worker/worker_status can find it again from a
+ * different process/session. Honors WEBFLOW_WORKER_PID_PATH, otherwise defaults to
+ * ~/.webflow/worker.pid.
+ */
+export declare function getWorkerPidPath(): string;
+/** stdout/stderr of the detached worker started by start_worker — there is no other
+ * way to see its output once the MCP tool call that launched it has returned. */
+export declare function getWorkerLogPath(): string;
+export declare function assertSupportedNode(version?: string): void;
+export declare function sanitizeName(input: string): string;
+export declare function getWorkspacePaths(projectRoot: string): WorkspacePaths;
+/**
+ * Resolve the workspace root that actually holds the flows, decoupled from the
+ * download/working root (Model B). Priority: WEBFLOW_FLOWS_DIR, then the calling
+ * repo if it has its own .webflow/flows, then the installed package's bundled flows.
+ * This lets an agent in any repo use the flows shipped here while its downloads stay
+ * in its own repo (the projectRoot).
+ */
+export declare function resolveFlowsProjectRoot(projectRoot: string): string;
+export declare function assertWorkspaceReady(projectRoot: string): Promise<void>;
+export declare function getPackageRoot(metaUrl: string): string;
+/**
+ * Gates the flow-author-only CLI commands (init/create/fork/doctor — scaffolding and
+ * diagnosing flows for the catalog, not something an end user running automations
+ * should ever see or reach). Detects the maintainer's own git checkout by checking
+ * for `.git` next to package.json — this can never end up in what an end user
+ * installs, because package.json's "files" field only ships `dist/src/` (never `.git`,
+ * never the top-level `src/`), so the check is a structural consequence of packaging
+ * itself, not a separate flag that could drift out of sync with it.
+ */
+export declare function isAuthorEnvironment(metaUrl: string): boolean;
+/** Split out from isAuthorEnvironment so tests can check the underlying rule (does
+ * this directory have a `.git`?) against a synthetic package root, without needing to
+ * fake an import.meta.url that resolves there via getPackageRoot's directory walk.
+ * `.git` is a DIRECTORY in a normal clone but a plain FILE (a `gitdir: ...` pointer)
+ * in a git worktree — this repo itself is checked out as a worktree, so checking
+ * `.isDirectory()` would wrongly say "not an author environment" on this very box.
+ * Either form only ever exists in a real git checkout, never in what an installed
+ * package extracts. */
+export declare function isAuthorPackageRoot(packageRoot: string): boolean;

package/dist/src/shared/paths.js

@@ -0,0 +1,257 @@
+import { dirname, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { WebFlowError } from './errors.js';
+export const MIN_NODE_MAJOR = 20;
+export const WORKFLOW_DIRNAME = '.webflow';
+/** Env var to override where login sessions (Chrome profiles) are stored. */
+export const PROFILES_DIR_ENV = 'WEBFLOW_PROFILES_DIR';
+/** Env var to override the workspace root that holds .webflow/flows (Model B cross-repo). */
+export const FLOWS_DIR_ENV = 'WEBFLOW_FLOWS_DIR';
+/** Env var to override where the global webflow-config.json (browser visibility, etc.) lives. */
+export const CONFIG_PATH_ENV = 'WEBFLOW_CONFIG_PATH';
+/** Env var to override where the local repertoire.json (saved flows) lives. */
+export const REPERTOIRE_PATH_ENV = 'WEBFLOW_REPERTOIRE_PATH';
+/** Env var to override persistent provider cooldown state. */
+export const ANTIBLOCK_DIR_ENV = 'WEBFLOW_ANTIBLOCK_DIR';
+/** Env var to override where the persisted relay login (~/.webflow/credentials.json) lives. */
+export const CREDENTIALS_PATH_ENV = 'WEBFLOW_CREDENTIALS_PATH';
+/** Env var to override the persistent device identity used during worker pairing. */
+export const DEVICE_IDENTITY_PATH_ENV = 'WEBFLOW_DEVICE_IDENTITY_PATH';
+/** Env vars for worker-local remote-flow trust decisions. */
+export const FLOW_APPROVALS_PATH_ENV = 'WEBFLOW_FLOW_APPROVALS_PATH';
+export const FLOW_PENDING_APPROVALS_PATH_ENV = 'WEBFLOW_FLOW_PENDING_APPROVALS_PATH';
+export const FLOW_RELEASE_STATE_PATH_ENV = 'WEBFLOW_FLOW_RELEASE_STATE_PATH';
+/** Independent MCP-client credentials used only by the local unified gateway. */
+export const RELAY_MCP_URL_ENV = 'WEBFLOW_RELAY_MCP_URL';
+export const RELAY_MCP_TOKEN_ENV = 'WEBFLOW_RELAY_MCP_TOKEN';
+/**
+ * Resolve the global profiles (login session) root, decoupled from any single
+ * repository. Honors WEBFLOW_PROFILES_DIR, otherwise defaults to ~/.webflow/profiles.
+ */
+export function getProfilesRoot() {
+    const override = process.env[PROFILES_DIR_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'profiles');
+}
+/**
+ * Resolve the global webflow-config.json path (browser visibility preferences, etc.),
+ * decoupled from any single repository — same rationale as getProfilesRoot(): the person
+ * running the worker has one set of preferences, not one per project. Honors
+ * WEBFLOW_CONFIG_PATH, otherwise defaults to ~/.webflow/config.json.
+ */
+export function getConfigPath() {
+    const override = process.env[CONFIG_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'config.json');
+}
+/**
+ * Resolve the global repertoire.json path (flows saved locally so the worker can expose
+ * them as direct tools without re-searching the catalog). Honors WEBFLOW_REPERTOIRE_PATH,
+ * otherwise defaults to ~/.webflow/repertoire.json.
+ */
+export function getRepertoirePath() {
+    const override = process.env[REPERTOIRE_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'repertoire.json');
+}
+export function getAntiBlockDir() {
+    const override = process.env[ANTIBLOCK_DIR_ENV];
+    if (override && override.trim().length > 0)
+        return resolve(override.trim());
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'anti-block');
+}
+/**
+ * Resolve the persisted worker-pairing path (`webflow login`'s relay URL + secret).
+ * Deliberately a SEPARATE file from config.json: that file is read wholesale
+ * and forwarded verbatim to MCP clients by the get_config tool (tool-registry.ts /
+ * mcp-endpoint.ts), so a worker secret must never live there. Honors
+ * WEBFLOW_CREDENTIALS_PATH, otherwise defaults to ~/.webflow/credentials.json.
+ */
+export function getCredentialsPath() {
+    const override = process.env[CREDENTIALS_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'credentials.json');
+}
+export function getDeviceIdentityPath() {
+    const override = process.env[DEVICE_IDENTITY_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'device.json');
+}
+export function getFlowApprovalsPath() {
+    const override = process.env[FLOW_APPROVALS_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'flow-approvals.json');
+}
+export function getFlowPendingApprovalsPath() {
+    const override = process.env[FLOW_PENDING_APPROVALS_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'flow-pending-approvals.json');
+}
+export function getFlowReleaseStatePath() {
+    const override = process.env[FLOW_RELEASE_STATE_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'flow-release-state.json');
+}
+/** Env var to override where the background worker's PID file lives (src/worker/lifecycle.ts). */
+export const WORKER_PID_PATH_ENV = 'WEBFLOW_WORKER_PID_PATH';
+/**
+ * Tracks the detached worker process started by the start_worker MCP tool
+ * (src/worker/lifecycle.ts), so stop_worker/worker_status can find it again from a
+ * different process/session. Honors WEBFLOW_WORKER_PID_PATH, otherwise defaults to
+ * ~/.webflow/worker.pid.
+ */
+export function getWorkerPidPath() {
+    const override = process.env[WORKER_PID_PATH_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    return resolve(homedir(), WORKFLOW_DIRNAME, 'worker.pid');
+}
+/** stdout/stderr of the detached worker started by start_worker — there is no other
+ * way to see its output once the MCP tool call that launched it has returned. */
+export function getWorkerLogPath() {
+    return resolve(dirname(getWorkerPidPath()), 'worker.log');
+}
+export function assertSupportedNode(version = process.versions.node) {
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    if (Number.isNaN(major) || major < MIN_NODE_MAJOR) {
+        throw new WebFlowError('UNSUPPORTED_NODE_VERSION', `WebFlow MCP requires Node ${MIN_NODE_MAJOR}+; detected ${version}.`, { version, required: `${MIN_NODE_MAJOR}+` });
+    }
+}
+export function sanitizeName(input) {
+    const normalized = input.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9_-]/g, '-').replace(/-+/g, '-');
+    const sanitized = normalized.replace(/^[-_.]+|[-_.]+$/g, '');
+    if (!sanitized) {
+        throw new WebFlowError('INVALID_NAME', `Invalid name: "${input}". Use letters, numbers, dashes, or underscores.`);
+    }
+    return sanitized;
+}
+export function getWorkspacePaths(projectRoot) {
+    const workspaceRoot = resolve(projectRoot, WORKFLOW_DIRNAME);
+    return {
+        projectRoot,
+        workspaceRoot,
+        flowsDir: resolve(workspaceRoot, 'flows'),
+        skillsDir: resolve(workspaceRoot, 'skills'),
+        // Sessions are global (log in once, reuse everywhere); downloads stay per-repo.
+        profilesDir: getProfilesRoot(),
+        downloadsDir: resolve(workspaceRoot, 'downloads'),
+        cacheDir: resolve(workspaceRoot, '.cache')
+    };
+}
+/**
+ * Resolve the workspace root that actually holds the flows, decoupled from the
+ * download/working root (Model B). Priority: WEBFLOW_FLOWS_DIR, then the calling
+ * repo if it has its own .webflow/flows, then the installed package's bundled flows.
+ * This lets an agent in any repo use the flows shipped here while its downloads stay
+ * in its own repo (the projectRoot).
+ */
+export function resolveFlowsProjectRoot(projectRoot) {
+    const override = process.env[FLOWS_DIR_ENV];
+    if (override && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    const root = resolve(projectRoot);
+    try {
+        if (statSync(resolve(root, WORKFLOW_DIRNAME, 'flows')).isDirectory()) {
+            return root;
+        }
+    }
+    catch {
+        // no local flows in the calling repo — fall through to the package's flows
+    }
+    try {
+        return getPackageRoot(import.meta.url);
+    }
+    catch {
+        return root;
+    }
+}
+export async function assertWorkspaceReady(projectRoot) {
+    const root = resolve(projectRoot);
+    try {
+        const rootStat = await stat(root);
+        if (!rootStat.isDirectory()) {
+            throw new Error('not a directory');
+        }
+    }
+    catch {
+        throw new WebFlowError('INVALID_PROJECT_ROOT', `Project root does not exist or is not a directory: ${root}`, { projectRoot: root });
+    }
+    const flowsRoot = resolveFlowsProjectRoot(root);
+    const paths = getWorkspacePaths(flowsRoot);
+    try {
+        const flowsStat = await stat(paths.flowsDir);
+        if (!flowsStat.isDirectory()) {
+            throw new Error('not a directory');
+        }
+    }
+    catch {
+        throw new WebFlowError('WORKSPACE_FLOWS_NOT_FOUND', `Workspace flows directory not found at ${paths.flowsDir}. Run webflow init, or set ${FLOWS_DIR_ENV} to a workspace that has .webflow/flows.`, { projectRoot: root, flowsDir: paths.flowsDir });
+    }
+}
+export function getPackageRoot(metaUrl) {
+    let current = dirname(fileURLToPath(metaUrl));
+    while (true) {
+        try {
+            statSync(resolve(current, 'package.json'));
+            statSync(resolve(current, '.webflow/flows/_template'));
+            return current;
+        }
+        catch {
+            const parent = resolve(current, '..');
+            if (parent === current) {
+                throw new WebFlowError('PACKAGE_ROOT_NOT_FOUND', 'Unable to resolve the WebFlow package root.');
+            }
+            current = parent;
+        }
+    }
+}
+/**
+ * Gates the flow-author-only CLI commands (init/create/fork/doctor — scaffolding and
+ * diagnosing flows for the catalog, not something an end user running automations
+ * should ever see or reach). Detects the maintainer's own git checkout by checking
+ * for `.git` next to package.json — this can never end up in what an end user
+ * installs, because package.json's "files" field only ships `dist/src/` (never `.git`,
+ * never the top-level `src/`), so the check is a structural consequence of packaging
+ * itself, not a separate flag that could drift out of sync with it.
+ */
+export function isAuthorEnvironment(metaUrl) {
+    return isAuthorPackageRoot(getPackageRoot(metaUrl));
+}
+/** Split out from isAuthorEnvironment so tests can check the underlying rule (does
+ * this directory have a `.git`?) against a synthetic package root, without needing to
+ * fake an import.meta.url that resolves there via getPackageRoot's directory walk.
+ * `.git` is a DIRECTORY in a normal clone but a plain FILE (a `gitdir: ...` pointer)
+ * in a git worktree — this repo itself is checked out as a worktree, so checking
+ * `.isDirectory()` would wrongly say "not an author environment" on this very box.
+ * Either form only ever exists in a real git checkout, never in what an installed
+ * package extracts. */
+export function isAuthorPackageRoot(packageRoot) {
+    try {
+        statSync(resolve(packageRoot, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/shared/semaphore.d.ts

@@ -0,0 +1,8 @@
+/** A simple counting semaphore with FIFO-ordered waiters. */
+export declare class Semaphore {
+    private available;
+    private readonly waiters;
+    constructor(permits: number);
+    acquire(): Promise<void>;
+    release(): void;
+}

package/dist/src/shared/semaphore.js

@@ -0,0 +1,23 @@
+/** A simple counting semaphore with FIFO-ordered waiters. */
+export class Semaphore {
+    available;
+    waiters = [];
+    constructor(permits) {
+        this.available = permits;
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+    }
+    release() {
+        const next = this.waiters.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.available += 1;
+    }
+}

package/dist/src/shared/taxonomy.d.ts

@@ -0,0 +1,21 @@
+export interface TaxonomyService {
+    label: string;
+    description?: string;
+}
+export interface TaxonomySector {
+    label: string;
+    services: Record<string, TaxonomyService>;
+}
+export interface Taxonomy {
+    sectors: Record<string, TaxonomySector>;
+}
+/**
+ * Loads the canonical sector/service registry (`taxonomy.json`, shipped at the package root
+ * alongside `package.json`). This is the single source of truth `webflow doctor` and
+ * `relay/scripts/sync-catalog.ts` validate `capabilities.category`/`capabilities.service`
+ * against — always resolved from this package's own install location, never from the
+ * `projectRoot` being audited, so it stays identical across every project that uses this CLI.
+ */
+export declare function loadTaxonomy(): Promise<Taxonomy>;
+export declare function isValidSector(taxonomy: Taxonomy, category: string): boolean;
+export declare function isValidService(taxonomy: Taxonomy, category: string, service: string): boolean;

package/dist/src/shared/taxonomy.js

@@ -0,0 +1,20 @@
+import { getPackageRoot } from './paths.js';
+import { readJsonFile } from './fs.js';
+import { resolve } from 'node:path';
+/**
+ * Loads the canonical sector/service registry (`taxonomy.json`, shipped at the package root
+ * alongside `package.json`). This is the single source of truth `webflow doctor` and
+ * `relay/scripts/sync-catalog.ts` validate `capabilities.category`/`capabilities.service`
+ * against — always resolved from this package's own install location, never from the
+ * `projectRoot` being audited, so it stays identical across every project that uses this CLI.
+ */
+export async function loadTaxonomy() {
+    const packageRoot = getPackageRoot(import.meta.url);
+    return readJsonFile(resolve(packageRoot, 'taxonomy.json'));
+}
+export function isValidSector(taxonomy, category) {
+    return category in taxonomy.sectors;
+}
+export function isValidService(taxonomy, category, service) {
+    return Boolean(taxonomy.sectors[category]?.services[service]);
+}

package/dist/src/worker/connection.d.ts

@@ -0,0 +1,72 @@
+import WebSocket from 'ws';
+import { type FlowTrustPolicyEntry } from '../security/flow-release.js';
+import type { WorkerService } from './worker-service.js';
+export interface WorkerConnectionOptions {
+    relayUrl: string;
+    credential: string;
+    workerId: string;
+    service: WorkerService;
+    trustPolicy?: readonly FlowTrustPolicyEntry[];
+    workerVersion?: string;
+    heartbeatIntervalMs?: number;
+    reconnectBaseDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+    onLog?: (message: string) => void;
+    /** Test hook: build the socket instead of dialing relayUrl for real. */
+    createSocket?: (url: string) => WebSocket;
+}
+/**
+ * Outbound WebSocket client that lets a local worker be driven by a remote relay
+ * without ever opening an inbound port on the user's machine (RFC 0001, section 2.1).
+ * Owns reconnection/backoff and heartbeating; all flow execution is delegated to
+ * WorkerService, which is the only piece that knows about FlowRunner/Chrome.
+ */
+export declare class WorkerConnection {
+    private readonly options;
+    private socket;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private stopped;
+    private helloSentSocket;
+    private authenticatedSocket;
+    constructor(options: WorkerConnectionOptions);
+    start(): void;
+    stop(): void;
+    private log;
+    private connect;
+    /**
+     * Sent on every connect AND every reconnect with the full catalog (never a diff),
+     * so a worker that changed its flows on disk never leaves the relay serving a
+     * stale tool list (RFC 0001, section 2.3).
+     */
+    private sendHello;
+    private send;
+    private startHeartbeat;
+    private clearHeartbeat;
+    private scheduleReconnect;
+    private handleMessage;
+    /**
+     * A dropped socket mid-job is an accepted v1 gap (RFC 0001, section 6, edge case 2):
+     * the flow keeps running locally against the user's real Chrome, but its result is
+     * bound to the socket that received the job. If that socket disconnects, the result
+     * is dropped instead of leaking into a new unauthenticated connection. Revisit before
+     * relying on this for anything
+     * business-critical.
+     */
+    private handleRun;
+    private rejectMalformedRun;
+    private runSignedRemoteFlow;
+    private approvalCommand;
+    /** Pure local disk I/O (~/.webflow/config.json) — should never take long enough for
+     * the relay's short request timeout to matter in practice. */
+    private handleConfigRequest;
+    /** Pure local disk I/O (~/.webflow/repertoire.json) — same near-instant expectation as config. */
+    private handleRepertoireRequest;
+    /**
+     * `login` opens a real, visible Chrome window and returns as soon as it's up
+     * (see WorkerService.startProfileLogin) — still well within the relay's short
+     * localRequestTimeoutMs, unlike waiting for the human to actually finish logging in.
+     */
+    private handleProfileRequest;
+}