webflow-mcp 0.3.0

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

@@ -0,0 +1,188 @@
+import type { SelfHealingPayload } from '../errors/self-healing.js';
+import type { CatalogEntry } from './worker-service.js';
+import type { WebflowConfig } from '../config/webflow-config.js';
+import type { BrowserVisibility, GlobalVisibilityPreference } from '../config/webflow-config.js';
+import type { BrowserMode } from '../runner/types.js';
+import type { SignedFlowRelease } from '../security/flow-release.js';
+export declare const WORKER_PROTOCOL_VERSION = 2;
+export declare const WORKER_VERSION = "0.3.0";
+export declare const SUPPORTED_FLOW_RELEASE_FORMATS: readonly [1];
+export declare const SUPPORTED_FLOW_RUNTIME_APIS: readonly [1];
+/**
+ * Wire contract between a local worker and the (future, out-of-repo) VPS relay.
+ * RFC 0001, section 2.3. This file is the source of truth for the message shapes;
+ * the relay implementation must keep its own copy in sync until/unless the types
+ * are published as a shared package.
+ *
+ * Deliberately NOT included in v1: a `run_progress` message. FlowModule.run()
+ * (src/runner/types.ts) has no progress-callback API, so there is nothing real to
+ * stream — adding progress messages here without a producer would be fake
+ * streaming. Add it to the flow contract first if this is ever needed.
+ */
+export interface HelloMessage {
+    type: 'hello';
+    workerId: string;
+    credential: string;
+    protocolVersion: typeof WORKER_PROTOCOL_VERSION;
+    workerVersion: string;
+    flowReleaseFormats: number[];
+    runtimeApiVersions: number[];
+    /**
+     * Locally-known flows only. Under the Fase 3 "everything is pushed" model (see
+     * `run.code` below) this is typically empty — the relay's own flow store is the
+     * catalog source of truth, not the worker. Kept for backward compat / diagnostics
+     * with the Fase 0-2 local-worker-catalog mode.
+     */
+    catalog: CatalogEntry[];
+}
+export interface HelloAckMessage {
+    type: 'hello_ack';
+    ok: boolean;
+    userId?: string;
+    reason?: string;
+}
+export interface RunMessage {
+    type: 'run';
+    jobId: string;
+    flow: string;
+    input: unknown;
+    /** Every network-originated run requires a signed immutable release artifact. */
+    release: SignedFlowRelease;
+    /** One-off execution overrides. Persisted preferences live in config_request. */
+    browserMode?: BrowserMode;
+    browserVisibility?: BrowserVisibility;
+}
+export interface RunResultMessage {
+    type: 'run_result';
+    jobId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: SelfHealingPayload;
+    /** See FlowExecutionSuccess.visibilityNudge (src/runner/types.ts) — carried over the
+     * wire so the relay can surface it as an `askUser` hint without a second round-trip. */
+    visibilityNudge?: string;
+}
+export interface PingMessage {
+    type: 'ping';
+}
+export interface PongMessage {
+    type: 'pong';
+}
+/**
+ * Config/repertoire live on the worker's own disk (never in the relay's database —
+ * same principle as login sessions/profiles). These four message types let the relay
+ * forward an agent's get/set calls to the worker that owns that state, and get a
+ * correlated reply back. Pure local disk I/O, so replies should be near-instant —
+ * see WorkerRegistry's separate short timeout for these (relay/src/worker-registry.ts),
+ * distinct from the multi-minute job timeout used for `run`.
+ */
+export type ConfigAction = {
+    action: 'get';
+} | {
+    action: 'set_default_visibility';
+    value: GlobalVisibilityPreference;
+} | {
+    action: 'set_flow_visibility';
+    flowName: string;
+    value: BrowserVisibility | null;
+} | {
+    action: 'set_default_browser_mode';
+    value: BrowserMode | 'inherit';
+} | {
+    action: 'set_flow_browser_mode';
+    flowName: string;
+    value: BrowserMode | null;
+};
+export interface ConfigRequestMessage {
+    type: 'config_request';
+    requestId: string;
+    request: ConfigAction;
+}
+export interface ConfigResponseMessage {
+    type: 'config_response';
+    requestId: string;
+    ok: boolean;
+    config?: WebflowConfig;
+    error?: string;
+}
+export type RepertoireAction = {
+    action: 'list';
+} | {
+    action: 'add';
+    flowName: string;
+} | {
+    action: 'remove';
+    flowName: string;
+};
+export interface RepertoireRequestMessage {
+    type: 'repertoire_request';
+    requestId: string;
+    request: RepertoireAction;
+}
+export interface RepertoireResponseMessage {
+    type: 'repertoire_response';
+    requestId: string;
+    ok: boolean;
+    flows?: string[];
+    error?: string;
+}
+/** Serializable mirror of ProfileStatusInfo (../profiles/profile-state.ts) — only the
+ * fields an MCP client needs, no local filesystem paths. */
+export interface ProfileStatusWire {
+    profileId: string;
+    status: 'missing' | 'exists_unverified' | 'setup_completed' | 'verified' | 'login_required';
+    probablyValid: boolean | 'unknown';
+    loginUrl?: string;
+    setupCommand: string;
+    lastInteractiveSetupAt?: string;
+    lastSuccessfulRunAt?: string;
+    lastLoginRequiredAt?: string | null;
+}
+/**
+ * Same disk-state principle as config/repertoire above (never the relay's database).
+ * `status` reads the last known state (fast, near-instant). `login` opens a real,
+ * visible Chrome window on this machine for the human to log in manually and returns
+ * as soon as the window is open — it does NOT wait for the user to finish (that can
+ * take minutes and must never hold up an MCP tool call). The worker keeps the
+ * per-profile lock held in the background until the window closes, so a flow run
+ * against the same profile can't start mid-login; call `status` again afterward to
+ * see whether it succeeded.
+ */
+export type ProfileAction = {
+    action: 'status';
+    flowName: string;
+    loginProvider?: string;
+    loginUrl?: string;
+} | {
+    action: 'login';
+    flowName: string;
+    loginProvider?: string;
+    loginUrl?: string;
+};
+export interface ProfileRequestMessage {
+    type: 'profile_request';
+    requestId: string;
+    request: ProfileAction;
+}
+export interface ProfileResponseMessage {
+    type: 'profile_response';
+    requestId: string;
+    ok: boolean;
+    status?: ProfileStatusWire;
+    /** Only set for the `login` action. */
+    launched?: boolean;
+    error?: string;
+}
+/** Messages the worker sends. */
+export type WorkerToRelayMessage = HelloMessage | RunResultMessage | PingMessage | PongMessage | ConfigResponseMessage | RepertoireResponseMessage | ProfileResponseMessage;
+/** Messages the worker receives. */
+export type RelayToWorkerMessage = HelloAckMessage | RunMessage | PingMessage | PongMessage | ConfigRequestMessage | RepertoireRequestMessage | ProfileRequestMessage;
+/**
+ * Defensive parse for messages arriving over the socket. A malformed or unexpected
+ * message from a misbehaving/compromised relay must never crash the worker process
+ * that also happens to be driving the user's real, logged-in Chrome (RFC 0001,
+ * section 5: don't trust the relay blindly). Throws WebFlowError on anything that
+ * doesn't match a known shape; callers should catch and drop the message.
+ */
+export declare function parseRelayToWorkerMessage(raw: string): RelayToWorkerMessage;
+export declare function serializeWorkerMessage(message: WorkerToRelayMessage): string;

package/dist/src/worker/protocol.js

@@ -0,0 +1,156 @@
+import { WebFlowError } from '../shared/errors.js';
+export const WORKER_PROTOCOL_VERSION = 2;
+export const WORKER_VERSION = '0.3.0';
+export const SUPPORTED_FLOW_RELEASE_FORMATS = [1];
+export const SUPPORTED_FLOW_RUNTIME_APIS = [1];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Defensive parse for messages arriving over the socket. A malformed or unexpected
+ * message from a misbehaving/compromised relay must never crash the worker process
+ * that also happens to be driving the user's real, logged-in Chrome (RFC 0001,
+ * section 5: don't trust the relay blindly). Throws WebFlowError on anything that
+ * doesn't match a known shape; callers should catch and drop the message.
+ */
+export function parseRelayToWorkerMessage(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new WebFlowError('INVALID_RELAY_MESSAGE', 'Message from relay is not valid JSON.');
+    }
+    if (!isRecord(parsed) || typeof parsed.type !== 'string') {
+        throw new WebFlowError('INVALID_RELAY_MESSAGE', 'Message from relay is missing a string "type" field.');
+    }
+    switch (parsed.type) {
+        case 'hello_ack':
+            if (typeof parsed.ok !== 'boolean') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'hello_ack message must have a boolean "ok" field.');
+            }
+            return {
+                type: 'hello_ack',
+                ok: parsed.ok,
+                userId: typeof parsed.userId === 'string' ? parsed.userId : undefined,
+                reason: typeof parsed.reason === 'string' ? parsed.reason : undefined
+            };
+        case 'run':
+            if (typeof parsed.jobId !== 'string' || typeof parsed.flow !== 'string') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'run message must have string "jobId" and "flow" fields.');
+            }
+            if (Object.hasOwn(parsed, 'code') || Object.hasOwn(parsed, 'schema') || Object.hasOwn(parsed, 'requiresLogin')
+                || Object.hasOwn(parsed, 'loginProvider') || Object.hasOwn(parsed, 'loginUrl')) {
+                throw new WebFlowError('FLOW_SIGNATURE_REQUIRED', 'Unsigned remote flow fields are no longer accepted.');
+            }
+            if (!isRecord(parsed.release)) {
+                throw new WebFlowError('FLOW_SIGNATURE_REQUIRED', 'Every remote run requires a signed flow release.');
+            }
+            return {
+                type: 'run',
+                jobId: parsed.jobId,
+                flow: parsed.flow,
+                input: parsed.input,
+                release: parsed.release,
+                browserMode: parsed.browserMode === 'managed' || parsed.browserMode === 'cdp' ? parsed.browserMode : undefined,
+                browserVisibility: parsed.browserVisibility === 'visible' || parsed.browserVisibility === 'hidden' ? parsed.browserVisibility : undefined
+            };
+        case 'ping':
+            return { type: 'ping' };
+        case 'pong':
+            return { type: 'pong' };
+        case 'config_request': {
+            if (typeof parsed.requestId !== 'string' || !isRecord(parsed.request) || typeof parsed.request.action !== 'string') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'config_request message must have a string "requestId" and a "request" object with an "action".');
+            }
+            const request = parseConfigAction(parsed.request);
+            return { type: 'config_request', requestId: parsed.requestId, request };
+        }
+        case 'repertoire_request': {
+            if (typeof parsed.requestId !== 'string' || !isRecord(parsed.request) || typeof parsed.request.action !== 'string') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'repertoire_request message must have a string "requestId" and a "request" object with an "action".');
+            }
+            const request = parseRepertoireAction(parsed.request);
+            return { type: 'repertoire_request', requestId: parsed.requestId, request };
+        }
+        case 'profile_request': {
+            if (typeof parsed.requestId !== 'string' || !isRecord(parsed.request) || typeof parsed.request.action !== 'string') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'profile_request message must have a string "requestId" and a "request" object with an "action".');
+            }
+            const request = parseProfileAction(parsed.request);
+            return { type: 'profile_request', requestId: parsed.requestId, request };
+        }
+        default:
+            throw new WebFlowError('INVALID_RELAY_MESSAGE', `Unknown message type from relay: "${parsed.type}".`);
+    }
+}
+function parseConfigAction(raw) {
+    switch (raw.action) {
+        case 'get':
+            return { action: 'get' };
+        case 'set_default_visibility':
+            if (raw.value !== 'visible' && raw.value !== 'hidden' && raw.value !== 'inherit') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_default_visibility requires value "visible", "hidden", or "inherit".');
+            }
+            return { action: 'set_default_visibility', value: raw.value };
+        case 'set_flow_visibility':
+            if (typeof raw.flowName !== 'string' || raw.flowName.length === 0) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_flow_visibility requires a non-empty "flowName".');
+            }
+            if (raw.value !== 'visible' && raw.value !== 'hidden' && raw.value !== null) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_flow_visibility requires value "visible", "hidden", or null.');
+            }
+            return { action: 'set_flow_visibility', flowName: raw.flowName, value: raw.value };
+        case 'set_default_browser_mode':
+            if (raw.value !== 'managed' && raw.value !== 'cdp' && raw.value !== 'inherit') {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_default_browser_mode requires value "managed", "cdp", or "inherit".');
+            }
+            return { action: 'set_default_browser_mode', value: raw.value };
+        case 'set_flow_browser_mode':
+            if (typeof raw.flowName !== 'string' || raw.flowName.length === 0) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_flow_browser_mode requires a non-empty "flowName".');
+            }
+            if (raw.value !== 'managed' && raw.value !== 'cdp' && raw.value !== null) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'set_flow_browser_mode requires value "managed", "cdp", or null.');
+            }
+            return { action: 'set_flow_browser_mode', flowName: raw.flowName, value: raw.value };
+        default:
+            throw new WebFlowError('INVALID_RELAY_MESSAGE', `Unknown config action: "${String(raw.action)}".`);
+    }
+}
+function parseRepertoireAction(raw) {
+    switch (raw.action) {
+        case 'list':
+            return { action: 'list' };
+        case 'add':
+            if (typeof raw.flowName !== 'string' || raw.flowName.length === 0) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'add requires a non-empty "flowName".');
+            }
+            return { action: 'add', flowName: raw.flowName };
+        case 'remove':
+            if (typeof raw.flowName !== 'string' || raw.flowName.length === 0) {
+                throw new WebFlowError('INVALID_RELAY_MESSAGE', 'remove requires a non-empty "flowName".');
+            }
+            return { action: 'remove', flowName: raw.flowName };
+        default:
+            throw new WebFlowError('INVALID_RELAY_MESSAGE', `Unknown repertoire action: "${String(raw.action)}".`);
+    }
+}
+function parseProfileAction(raw) {
+    if (typeof raw.flowName !== 'string' || raw.flowName.length === 0) {
+        throw new WebFlowError('INVALID_RELAY_MESSAGE', `${String(raw.action)} requires a non-empty "flowName".`);
+    }
+    const loginProvider = typeof raw.loginProvider === 'string' ? raw.loginProvider : undefined;
+    const loginUrl = typeof raw.loginUrl === 'string' ? raw.loginUrl : undefined;
+    switch (raw.action) {
+        case 'status':
+            return { action: 'status', flowName: raw.flowName, loginProvider, loginUrl };
+        case 'login':
+            return { action: 'login', flowName: raw.flowName, loginProvider, loginUrl };
+        default:
+            throw new WebFlowError('INVALID_RELAY_MESSAGE', `Unknown profile action: "${String(raw.action)}".`);
+    }
+}
+export function serializeWorkerMessage(message) {
+    return JSON.stringify(message);
+}

package/dist/src/worker/worker-service.d.ts

@@ -0,0 +1,112 @@
+import { FlowRunner } from '../runner/flow-runner.js';
+import type { FlowRunOptions } from '../runner/flow-runner.js';
+import type { BrowserMode, FlowExecutionResult } from '../runner/types.js';
+import type { ProfileStatusInfo } from '../profiles/profile-state.js';
+import type { SupportedSchema } from '../schema/types.js';
+import type { BrowserVisibility, GlobalBrowserModePreference, GlobalVisibilityPreference, WebflowConfig } from '../config/webflow-config.js';
+import { type VerifiedRemoteFlow } from '../security/flow-release.js';
+/**
+ * What a worker reports to the relay so it can register MCP tools on the worker's
+ * behalf. Mirrors the same schema/description resolution tool-registry.ts already
+ * does for the local stdio path (RFC 0001, section 2.2). `requiresLogin`/`loginProvider`
+ * mirror the flow's `capabilities.requiresLogin`/`capabilities.profile` so a future
+ * relay/dashboard can tell a user "connect this account first" instead of guessing.
+ */
+export interface CatalogEntry {
+    name: string;
+    description: string;
+    inputSchema: SupportedSchema;
+    requiresLogin: boolean;
+    loginProvider?: string;
+    loginUrl?: string;
+    defaultBrowserMode?: BrowserMode;
+    supportedBrowserModes?: BrowserMode[];
+}
+export interface WorkerServiceOptions {
+    /** Inject a runner (tests); defaults to a real FlowRunner over projectRoot. */
+    runner?: FlowRunner;
+    /**
+     * Local, worker-owner-controlled default for whether Chrome is visible. The remote
+     * relay/client has no channel to override this — only the person watching their own
+     * screen decides (see RFC 0001 follow-up, 2026-07-06). Defaults to headless (false).
+     */
+    headed?: boolean;
+    browserMode?: BrowserMode;
+    browserVisibility?: BrowserVisibility;
+}
+/**
+ * Local, network-agnostic execution surface for the worker transport (RFC 0001,
+ * Fase 0/1). Delegates every bit of actual execution to the existing
+ * FlowRunner/discoverFlows — this class only adds catalog building, a per-profile
+ * lock, and a login pre-check, none of which existed before because a single stdio
+ * client never called runFlow twice concurrently and always ran with a human at the
+ * keyboard to notice a login wall.
+ */
+export declare class WorkerService {
+    private readonly projectRoot;
+    private readonly runner;
+    private readonly headed?;
+    private readonly browserMode?;
+    private readonly browserVisibility?;
+    private flowsByName;
+    private loginMetaByName;
+    private locks;
+    constructor(projectRoot: string, options?: WorkerServiceOptions);
+    /**
+     * Discovers flows, compiles their schemas, and loads each flow module once to read
+     * its `capabilities` (requiresLogin/profile). Refreshes the internal catalog used by
+     * runFlow(). Call again after reconnecting to a relay so a stale catalog (e.g. a flow
+     * removed from disk) never lingers (RFC 0001, section 2.3: reconnection resends the
+     * full catalog; the relay overwrites, never merges).
+     */
+    buildCatalog(): Promise<CatalogEntry[]>;
+    /**
+     * Runs a flow by name against the catalog built by buildCatalog(). Two safety nets
+     * that a single local stdio client never needed:
+     *
+     * 1. Login pre-check: if the flow declares `requiresLogin: true` and its resolved
+     *    profile directory does not exist yet, fails fast with a `LOGIN_REQUIRED` error
+     *    instead of letting Playwright launch a fresh, unauthenticated Chrome and time
+     *    out minutes later on a login wall with a confusing generic error.
+     * 2. Per-profile lock: serializes concurrent calls that resolve to the same profile
+     *    so two jobs never race to launch Chrome against the same user-data-dir (one
+     *    userDataDir = one process at a time; see modules/sessions-y-profiles.md).
+     */
+    runFlow(name: string, input: unknown, options?: FlowRunOptions): Promise<FlowExecutionResult>;
+    /**
+     * Runs a flow whose code the relay pushed alongside the job (RFC 0001, Fase 3) —
+     * there is no local flow definition to look up at all, by design: nothing, paid or
+     * free, is meant to persist on this machine. Reuses the same login pre-check and
+     * per-profile lock as runFlow(); only where the module comes from differs.
+     */
+    runVerifiedRemoteFlow(verified: VerifiedRemoteFlow, input: unknown, options?: FlowRunOptions): Promise<FlowExecutionResult>;
+    /**
+     * Config/repertoire are worker-local disk state (~/.webflow/config.json,
+     * ~/.webflow/repertoire.json) — never the relay's database, same principle as
+     * login sessions/profiles. These are the only entry points the relay's forwarded
+     * config_request/repertoire_request messages call into (see connection.ts). Reuse
+     * the same enqueue() lock used for flow runs, under fixed keys, so two concurrent
+     * requests never race writing the same file.
+     */
+    getConfig(): Promise<WebflowConfig>;
+    setDefaultBrowserVisibility(value: GlobalVisibilityPreference): Promise<WebflowConfig>;
+    setFlowBrowserVisibility(flowName: string, value: BrowserVisibility | null): Promise<WebflowConfig>;
+    setDefaultBrowserMode(value: GlobalBrowserModePreference): Promise<WebflowConfig>;
+    setFlowBrowserMode(flowName: string, value: BrowserMode | null): Promise<WebflowConfig>;
+    listRepertoire(): Promise<string[]>;
+    /** Fast, read-only disk check — same status a running flow would see before deciding LOGIN_REQUIRED. */
+    checkProfileStatus(flowName: string, loginProvider?: string, loginUrl?: string): Promise<ProfileStatusInfo>;
+    /**
+     * Opens a real, visible Chrome window on this machine for the human to log in
+     * manually, then returns as soon as the window is up — it does not wait for them
+     * to finish (that can take minutes, far too long for an MCP tool call). The
+     * per-profile lock (same one runFlow/runRemoteFlow use) is still held for the full
+     * session in the background, so an automated run against this profile can't start
+     * mid-login; call checkProfileStatus afterward to see whether it succeeded.
+     */
+    startProfileLogin(flowName: string, loginProvider?: string, loginUrl?: string): Promise<ProfileStatusInfo>;
+    addToRepertoire(flowName: string): Promise<string[]>;
+    removeFromRepertoire(flowName: string): Promise<string[]>;
+    private enqueue;
+    private resolveProfileName;
+}