webflow-mcp 0.3.0

package/dist/src/worker/connection.js

@@ -0,0 +1,427 @@
+import WebSocket from 'ws';
+import { buildSelfHealingPayload } from '../errors/self-healing.js';
+import { assertSecureRelayUrl } from '../shared/credentials.js';
+import { WebFlowError } from '../shared/errors.js';
+import { verifyFlowRelease } from '../security/flow-release.js';
+import { parseRelayToWorkerMessage, serializeWorkerMessage, SUPPORTED_FLOW_RELEASE_FORMATS, SUPPORTED_FLOW_RUNTIME_APIS, WORKER_PROTOCOL_VERSION, WORKER_VERSION } from './protocol.js';
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 20_000;
+const DEFAULT_RECONNECT_BASE_DELAY_MS = 1_000;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 30_000;
+const MAX_RELAY_FRAME_BYTES = 6 * 1024 * 1024;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 class WorkerConnection {
+    options;
+    socket;
+    heartbeatTimer;
+    reconnectTimer;
+    reconnectAttempt = 0;
+    stopped = true;
+    helloSentSocket;
+    authenticatedSocket;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        assertSecureRelayUrl(this.options.relayUrl);
+        this.stopped = false;
+        this.reconnectAttempt = 0;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.helloSentSocket = undefined;
+        this.authenticatedSocket = undefined;
+        this.clearHeartbeat();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        this.socket?.close();
+    }
+    log(message) {
+        this.options.onLog?.(message);
+    }
+    connect() {
+        const createSocket = this.options.createSocket ?? ((url) => new WebSocket(url, { maxPayload: MAX_RELAY_FRAME_BYTES }));
+        const socket = createSocket(this.options.relayUrl);
+        this.socket = socket;
+        this.helloSentSocket = undefined;
+        this.authenticatedSocket = undefined;
+        socket.on('open', () => {
+            if (socket !== this.socket || this.stopped) {
+                socket.close();
+                return;
+            }
+            this.reconnectAttempt = 0;
+            this.log(`connected to relay at ${this.options.relayUrl}`);
+            void this.sendHello(socket).catch((error) => {
+                this.log(`could not prepare worker hello: ${error instanceof Error ? error.message : String(error)}`);
+                socket.close(1011, 'could not prepare hello');
+            });
+        });
+        socket.on('message', (data, isBinary) => {
+            if (isBinary) {
+                socket.close(1003, 'binary relay messages are not supported');
+                return;
+            }
+            void this.handleMessage(socket, data.toString());
+        });
+        socket.on('close', () => {
+            if (socket !== this.socket)
+                return;
+            this.helloSentSocket = undefined;
+            this.authenticatedSocket = undefined;
+            this.clearHeartbeat();
+            if (!this.stopped) {
+                this.log('relay connection closed; scheduling reconnect');
+                this.scheduleReconnect();
+            }
+        });
+        socket.on('error', (error) => {
+            this.log(`relay connection error: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /**
+     * 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).
+     */
+    async sendHello(socket) {
+        const catalog = await this.options.service.buildCatalog();
+        if (socket !== this.socket || this.stopped)
+            return;
+        this.send({
+            type: 'hello',
+            workerId: this.options.workerId,
+            credential: this.options.credential,
+            protocolVersion: WORKER_PROTOCOL_VERSION,
+            workerVersion: this.options.workerVersion ?? WORKER_VERSION,
+            flowReleaseFormats: [...SUPPORTED_FLOW_RELEASE_FORMATS],
+            runtimeApiVersions: [...SUPPORTED_FLOW_RUNTIME_APIS],
+            catalog
+        }, socket);
+        this.helloSentSocket = socket;
+    }
+    send(message, socket = this.socket) {
+        if (socket?.readyState === WebSocket.OPEN) {
+            socket.send(serializeWorkerMessage(message));
+        }
+    }
+    startHeartbeat(socket) {
+        this.clearHeartbeat();
+        const intervalMs = this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        // Heartbeat is independent of job traffic: a multi-minute flow run must never
+        // be mistaken for a dead connection (RFC 0001, section 3.1).
+        this.heartbeatTimer = setInterval(() => {
+            if (socket === this.socket && socket === this.authenticatedSocket) {
+                this.send({ type: 'ping' }, socket);
+            }
+        }, intervalMs);
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    scheduleReconnect() {
+        const base = this.options.reconnectBaseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS;
+        const max = this.options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
+        const delay = Math.min(max, base * 2 ** this.reconnectAttempt);
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            if (!this.stopped) {
+                this.connect();
+            }
+        }, delay);
+    }
+    async handleMessage(socket, raw) {
+        if (socket !== this.socket)
+            return;
+        let message;
+        try {
+            message = parseRelayToWorkerMessage(raw);
+        }
+        catch (error) {
+            this.log(`ignoring malformed message from relay: ${error instanceof Error ? error.message : String(error)}`);
+            this.rejectMalformedRun(socket, raw, error);
+            return;
+        }
+        if (message.type === 'hello_ack') {
+            if (this.helloSentSocket !== socket) {
+                this.log('closing relay connection: received hello_ack before hello was sent');
+                socket.close(4002, 'unexpected hello acknowledgement');
+                return;
+            }
+            if (this.authenticatedSocket === socket) {
+                this.log('closing relay connection: duplicate hello_ack');
+                socket.close(4002, 'hello already acknowledged');
+                return;
+            }
+            if (!message.ok) {
+                this.log(`relay rejected hello: ${message.reason ?? 'unknown reason'}`);
+                if (/invalid|revoked/i.test(message.reason ?? '')) {
+                    this.stopped = true;
+                    this.clearHeartbeat();
+                    this.log('worker stopped because the saved credential is invalid or revoked; run "webflow login" to pair again');
+                }
+                socket.close(4003, 'hello rejected');
+                return;
+            }
+            this.authenticatedSocket = socket;
+            this.startHeartbeat(socket);
+            this.log('relay authenticated this worker connection');
+            return;
+        }
+        // Heartbeat frames are harmless while the relay is still validating hello. Every
+        // operation with local side effects remains blocked until a positive ack arrives.
+        if (message.type === 'ping') {
+            this.send({ type: 'pong' }, socket);
+            return;
+        }
+        if (message.type === 'pong')
+            return;
+        if (this.authenticatedSocket !== socket) {
+            this.log(`closing relay connection: received ${message.type} before authentication`);
+            socket.close(4003, 'relay not authenticated');
+            return;
+        }
+        switch (message.type) {
+            case 'run':
+                await this.handleRun(socket, message);
+                return;
+            case 'config_request':
+                await this.handleConfigRequest(socket, message);
+                return;
+            case 'repertoire_request':
+                await this.handleRepertoireRequest(socket, message);
+                return;
+            case 'profile_request':
+                await this.handleProfileRequest(socket, message);
+                return;
+        }
+    }
+    /**
+     * 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.
+     */
+    async handleRun(socket, message) {
+        try {
+            const result = await this.runSignedRemoteFlow(message);
+            if (result.ok) {
+                this.send({ type: 'run_result', jobId: message.jobId, ok: true, result: result.result, visibilityNudge: result.visibilityNudge }, socket);
+            }
+            else {
+                this.send({ type: 'run_result', jobId: message.jobId, ok: false, error: result.error }, socket);
+            }
+        }
+        catch (error) {
+            // WebFlowError already carries a meaningful code (FLOW_NOT_FOUND, LOGIN_REQUIRED,
+            // ...) from WorkerService — surface it as-is instead of relabeling everything.
+            const code = error instanceof WebFlowError ? error.code : 'WORKER_RUN_FAILED';
+            const details = error instanceof WebFlowError
+                ? error.details
+                : undefined;
+            const approvalCommand = code === 'FLOW_UPDATE_APPROVAL_REQUIRED'
+                ? this.approvalCommand(message.flow, details?.trustDomain)
+                : undefined;
+            this.send({
+                type: 'run_result',
+                jobId: message.jobId,
+                ok: false,
+                error: buildSelfHealingPayload(error, {
+                    code,
+                    flow: message.flow,
+                    profile: details?.profile,
+                    profileStatus: details?.profileStatus,
+                    loginUrl: details?.loginUrl,
+                    setupCommand: approvalCommand ?? details?.setupCommand,
+                    approvalCommand,
+                    flowDigest: details?.flowDigest,
+                    releaseId: details?.releaseId,
+                    releaseVersion: details?.releaseVersion,
+                    releaseSequence: details?.releaseSequence,
+                    signerKeyId: details?.signerKeyId,
+                    trustDomain: details?.trustDomain,
+                    retryable: false,
+                    suggestedAction: approvalCommand
+                        ? `On the worker machine, use the local MCP tools list_flow_approvals and approve_flow_update after explicit user confirmation, or run "${approvalCommand}" in an interactive terminal, then retry.`
+                        : 'Verify the flow name/login state against this worker\'s catalog and its saved sessions.'
+                })
+            }, socket);
+        }
+    }
+    rejectMalformedRun(socket, raw, error) {
+        let candidate;
+        try {
+            candidate = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!candidate || typeof candidate !== 'object' || candidate.type !== 'run')
+            return;
+        if (this.authenticatedSocket !== socket) {
+            socket.close(4003, 'relay not authenticated');
+            return;
+        }
+        const record = candidate;
+        if (typeof record.jobId !== 'string' || typeof record.flow !== 'string')
+            return;
+        const code = error instanceof WebFlowError ? error.code : 'INVALID_RELAY_MESSAGE';
+        this.send({
+            type: 'run_result',
+            jobId: record.jobId,
+            ok: false,
+            error: buildSelfHealingPayload(error, {
+                code,
+                flow: record.flow,
+                retryable: false,
+                suggestedAction: 'Update the relay/worker and retry with a valid signed flow release.'
+            })
+        }, socket);
+    }
+    async runSignedRemoteFlow(message) {
+        const policies = (this.options.trustPolicy ?? []).filter((entry) => entry.relayUrl === this.options.relayUrl);
+        const domains = [...new Set(policies.map((entry) => entry.trustDomain))];
+        if (domains.length !== 1) {
+            throw new WebFlowError('UNTRUSTED_FLOW_RELEASE', `No unique flow trust policy is configured for ${this.options.relayUrl}.`);
+        }
+        const verified = verifyFlowRelease(message.release, {
+            expectedRelayUrl: this.options.relayUrl,
+            expectedTrustDomain: domains[0],
+            trustPolicy: policies
+        });
+        if (verified.flowName !== message.flow) {
+            throw new WebFlowError('FLOW_RELEASE_NAME_MISMATCH', 'The signed flow name does not match the requested flow.');
+        }
+        try {
+            return await this.options.service.runVerifiedRemoteFlow(verified, message.input, { browserMode: message.browserMode, browserVisibility: message.browserVisibility });
+        }
+        catch (error) {
+            if (error instanceof WebFlowError && error.code === 'FLOW_UPDATE_APPROVAL_REQUIRED') {
+                const details = isRecord(error.details) ? error.details : {};
+                throw new WebFlowError(error.code, error.message, {
+                    ...details,
+                    flowDigest: verified.flowDigest,
+                    releaseId: verified.releaseId,
+                    releaseVersion: verified.version,
+                    releaseSequence: verified.sequence,
+                    signerKeyId: verified.keyId,
+                    trustDomain: verified.trustDomain
+                });
+            }
+            throw error;
+        }
+    }
+    approvalCommand(flowName, trustDomain) {
+        const quote = (value) => /^[a-zA-Z0-9._-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+        return `webflow approvals approve ${quote(flowName)}${trustDomain ? ` --trust-domain ${quote(trustDomain)}` : ''}`;
+    }
+    /** Pure local disk I/O (~/.webflow/config.json) — should never take long enough for
+     * the relay's short request timeout to matter in practice. */
+    async handleConfigRequest(socket, message) {
+        try {
+            const config = await (async () => {
+                switch (message.request.action) {
+                    case 'get':
+                        return this.options.service.getConfig();
+                    case 'set_default_visibility':
+                        return this.options.service.setDefaultBrowserVisibility(message.request.value);
+                    case 'set_flow_visibility':
+                        return this.options.service.setFlowBrowserVisibility(message.request.flowName, message.request.value);
+                    case 'set_default_browser_mode':
+                        return this.options.service.setDefaultBrowserMode(message.request.value);
+                    case 'set_flow_browser_mode':
+                        return this.options.service.setFlowBrowserMode(message.request.flowName, message.request.value);
+                }
+            })();
+            this.send({ type: 'config_response', requestId: message.requestId, ok: true, config }, socket);
+        }
+        catch (error) {
+            this.send({
+                type: 'config_response',
+                requestId: message.requestId,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            }, socket);
+        }
+    }
+    /** Pure local disk I/O (~/.webflow/repertoire.json) — same near-instant expectation as config. */
+    async handleRepertoireRequest(socket, message) {
+        try {
+            const flows = await (async () => {
+                switch (message.request.action) {
+                    case 'list':
+                        return this.options.service.listRepertoire();
+                    case 'add':
+                        return this.options.service.addToRepertoire(message.request.flowName);
+                    case 'remove':
+                        return this.options.service.removeFromRepertoire(message.request.flowName);
+                }
+            })();
+            this.send({ type: 'repertoire_response', requestId: message.requestId, ok: true, flows }, socket);
+        }
+        catch (error) {
+            this.send({
+                type: 'repertoire_response',
+                requestId: message.requestId,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            }, socket);
+        }
+    }
+    /**
+     * `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.
+     */
+    async handleProfileRequest(socket, message) {
+        try {
+            const status = await (async () => {
+                switch (message.request.action) {
+                    case 'status':
+                        return this.options.service.checkProfileStatus(message.request.flowName, message.request.loginProvider, message.request.loginUrl);
+                    case 'login':
+                        return this.options.service.startProfileLogin(message.request.flowName, message.request.loginProvider, message.request.loginUrl);
+                }
+            })();
+            this.send({
+                type: 'profile_response',
+                requestId: message.requestId,
+                ok: true,
+                launched: message.request.action === 'login' ? true : undefined,
+                status: {
+                    profileId: status.profileId,
+                    status: status.status,
+                    probablyValid: status.probablyValid,
+                    loginUrl: status.loginUrl,
+                    setupCommand: status.setupCommand,
+                    lastInteractiveSetupAt: status.lastInteractiveSetupAt,
+                    lastSuccessfulRunAt: status.lastSuccessfulRunAt,
+                    lastLoginRequiredAt: status.lastLoginRequiredAt
+                }
+            }, socket);
+        }
+        catch (error) {
+            this.send({
+                type: 'profile_response',
+                requestId: message.requestId,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            }, socket);
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { BrowserMode } from '../runner/types.js';
+import type { BrowserVisibility } from '../config/webflow-config.js';
+export interface WorkerProcessInfo {
+    pid: number;
+    startedAt: string;
+    relayUrl: string;
+}
+export interface StartWorkerOptions {
+    headed?: boolean;
+    browserMode?: BrowserMode;
+    browserVisibility?: BrowserVisibility;
+    /** Test hook: spawn this instead of the real dist/src/cli/index.js. */
+    cliEntryPath?: string;
+}
+export type StartWorkerResult = {
+    started: true;
+    pid: number;
+    relayUrl: string;
+} | {
+    started: false;
+    alreadyRunning: true;
+    pid: number;
+} | {
+    started: false;
+    alreadyRunning?: false;
+    reason: string;
+};
+export type StopWorkerResult = {
+    stopped: true;
+    pid: number;
+} | {
+    stopped: false;
+    reason: string;
+};
+/** Also self-heals a stale PID file (process no longer alive) by clearing it, so
+ * callers never have to special-case "file exists but process is dead". */
+export declare function isWorkerRunning(): Promise<WorkerProcessInfo | undefined>;
+/**
+ * Launches `webflow worker start` as a detached background process and returns as
+ * soon as it's confirmed alive, without waiting for it to actually finish connecting
+ * (that stays connected indefinitely by design). Deliberately never accepts a relay
+ * URL or secret argument — it only ever uses what `webflow login` already persisted,
+ * so a chat-connected MCP client can start/stop the worker without ever handling the
+ * worker secret itself.
+ */
+export declare function startBackgroundWorker(options?: StartWorkerOptions): Promise<StartWorkerResult>;
+/** Best-effort graceful stop: SIGTERM, then wait briefly for the process to actually
+ * exit before clearing the PID file, matching the CLI's own SIGTERM/SIGINT handler
+ * (src/cli/index.ts) which closes the relay connection cleanly. */
+export declare function stopBackgroundWorker(timeoutMs?: number): Promise<StopWorkerResult>;

package/dist/src/worker/lifecycle.js

@@ -0,0 +1,154 @@
+import { closeSync, openSync } from 'node:fs';
+import { readFile, rm } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { loadCredentials } from '../shared/credentials.js';
+import { ensureDir, writeJsonFile } from '../shared/fs.js';
+import { getPackageRoot, getWorkerLogPath, getWorkerPidPath, RELAY_MCP_TOKEN_ENV } from '../shared/paths.js';
+/**
+ * Login is a delicate, one-time step for many users — spell out each step in order
+ * instead of a terse pointer, since whoever is reading this on the other end may
+ * never have opened a terminal for this before. Never invite the agent to ask for or
+ * handle a worker secret itself; pairing happens in the user's browser.
+ */
+const NOT_LOGGED_IN_MESSAGE = 'This machine has not logged in to a relay yet, so the worker cannot start. Walk the user through these ' +
+    'exact steps, one at a time, and wait for them to confirm each before moving to the next — do not skip ahead ' +
+    'and do not ask them to paste any credential here or anywhere in this chat:\n' +
+    '1. Ask them to open a terminal ON THEIR OWN MACHINE (not this chat) and run exactly:\n' +
+    '   webflow login\n' +
+    '2. Their browser will open the WebFlowMCP app. Ask them to approve the displayed device pairing.\n' +
+    '3. Once the command confirms the pairing, tell them to let you know, then call start_worker again.';
+function isPidAlive(pid) {
+    try {
+        // Signal 0 sends nothing — it only probes whether the process exists and is
+        // ours to signal (throws ESRCH/EPERM otherwise). Never actually kills anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPidFile() {
+    try {
+        const raw = await readFile(getWorkerPidPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== 'number' || typeof parsed.startedAt !== 'string' || typeof parsed.relayUrl !== 'string') {
+            return undefined;
+        }
+        return { pid: parsed.pid, startedAt: parsed.startedAt, relayUrl: parsed.relayUrl };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function clearPidFile() {
+    await rm(getWorkerPidPath(), { force: true });
+}
+/** Also self-heals a stale PID file (process no longer alive) by clearing it, so
+ * callers never have to special-case "file exists but process is dead". */
+export async function isWorkerRunning() {
+    const info = await readPidFile();
+    if (!info)
+        return undefined;
+    if (!isPidAlive(info.pid)) {
+        await clearPidFile();
+        return undefined;
+    }
+    return info;
+}
+async function readLogTail(logPath, maxChars = 2000) {
+    try {
+        const raw = await readFile(logPath, 'utf8');
+        return raw.length > maxChars ? raw.slice(-maxChars) : raw;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Launches `webflow worker start` as a detached background process and returns as
+ * soon as it's confirmed alive, without waiting for it to actually finish connecting
+ * (that stays connected indefinitely by design). Deliberately never accepts a relay
+ * URL or secret argument — it only ever uses what `webflow login` already persisted,
+ * so a chat-connected MCP client can start/stop the worker without ever handling the
+ * worker secret itself.
+ */
+export async function startBackgroundWorker(options = {}) {
+    const existing = await isWorkerRunning();
+    if (existing) {
+        return { started: false, alreadyRunning: true, pid: existing.pid };
+    }
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        return {
+            started: false,
+            reason: NOT_LOGGED_IN_MESSAGE
+        };
+    }
+    const cliEntryPath = options.cliEntryPath ?? resolve(getPackageRoot(import.meta.url), 'dist/src/cli/index.js');
+    const logPath = getWorkerLogPath();
+    await ensureDir(dirname(logPath));
+    const logFd = openSync(logPath, 'a');
+    const args = ['worker', 'start'];
+    if (options.headed)
+        args.push('--headed');
+    if (options.browserMode)
+        args.push('--browser-mode', options.browserMode);
+    if (options.browserVisibility)
+        args.push('--browser-visibility', options.browserVisibility);
+    const childEnvironment = { ...process.env };
+    delete childEnvironment[RELAY_MCP_TOKEN_ENV];
+    const child = spawn(process.execPath, [cliEntryPath, ...args], {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        env: childEnvironment
+    });
+    closeSync(logFd); // The child inherited its own copy; this process no longer needs it.
+    child.unref(); // Survives after this MCP tool call — and this whole session — ends.
+    // Give it a moment to fail fast (bad relay URL, corrupt credentials, port issues)
+    // before declaring success, instead of blindly trusting a fire-and-forget spawn.
+    const crashed = await new Promise((resolveCrash) => {
+        let settled = false;
+        child.once('exit', () => {
+            if (!settled) {
+                settled = true;
+                resolveCrash(true);
+            }
+        });
+        setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolveCrash(false);
+            }
+        }, 1500);
+    });
+    if (crashed || typeof child.pid !== 'number') {
+        const tail = await readLogTail(logPath);
+        return { started: false, reason: `Worker process exited immediately.${tail ? ` Last log output:\n${tail}` : ''}` };
+    }
+    await writeJsonFile(getWorkerPidPath(), { pid: child.pid, startedAt: new Date().toISOString(), relayUrl: credentials.relayUrl });
+    return { started: true, pid: child.pid, relayUrl: credentials.relayUrl };
+}
+/** Best-effort graceful stop: SIGTERM, then wait briefly for the process to actually
+ * exit before clearing the PID file, matching the CLI's own SIGTERM/SIGINT handler
+ * (src/cli/index.ts) which closes the relay connection cleanly. */
+export async function stopBackgroundWorker(timeoutMs = 5_000) {
+    const info = await isWorkerRunning();
+    if (!info) {
+        return { stopped: false, reason: 'No worker is currently running.' };
+    }
+    try {
+        process.kill(info.pid, 'SIGTERM');
+    }
+    catch (error) {
+        await clearPidFile();
+        return { stopped: false, reason: `Could not signal process ${info.pid}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && isPidAlive(info.pid)) {
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    await clearPidFile();
+    return { stopped: true, pid: info.pid };
+}