@tomflow/proflow-execution-browser-extension 0.1.12 → 0.1.13

package/dist/src/custom-gpt-provisioner.js

@@ -0,0 +1,225 @@
+import { readFile, rm } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { readModuleSharedFacts } from "@tomflow/proflow-module-contract";
+import { materializeCustomGptKnowledgeBundle, } from "./custom-gpt-knowledge.js";
+import { createCustomGptProvisioningBridgeServer, } from "./provisioning-bridge.js";
+function packageAsset(packageRoot, asset, name) {
+    if (asset.length === 0 || isAbsolute(asset))
+        throw new Error(`${name}_INVALID`);
+    const root = resolve(packageRoot);
+    const path = resolve(root, asset);
+    const rel = relative(root, path);
+    if (rel === "" ||
+        rel === ".." ||
+        rel.startsWith(`..${sep}`) ||
+        isAbsolute(rel))
+        throw new Error(`${name}_OUTSIDE_PACKAGE`);
+    return path;
+}
+function publicGatewayUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("GATEWAY_URL_INVALID");
+    }
+    if (url.protocol !== "https:" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "")
+        throw new Error("GATEWAY_URL_INVALID");
+    return url.toString().replace(/\/$/, "");
+}
+function hydratedSchema(schema, gatewayUrl) {
+    const gateway = publicGatewayUrl(gatewayUrl);
+    if (schema.includes("https://GATEWAY_PUBLIC_HOST"))
+        return schema.replaceAll("https://GATEWAY_PUBLIC_HOST", gateway);
+    if (!schema.includes(gateway))
+        throw new Error("ACTION_SCHEMA_GATEWAY_MISMATCH");
+    return schema;
+}
+function fileEvidence(files) {
+    return files.map(({ name, mime, sizeBytes, sha256 }) => ({
+        name,
+        mime,
+        sizeBytes,
+        sha256,
+    }));
+}
+function liveResult(value, material) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("PROVISIONING_RESULT_INVALID");
+    const result = value;
+    if (result.status !== "LIVE_CREATED" ||
+        result.packageName !== material.packageName ||
+        result.version !== material.version ||
+        typeof result.gptId !== "string" ||
+        !/^g-[A-Za-z0-9_-]+$/.test(result.gptId) ||
+        typeof result.carrierUrl !== "string")
+        throw new Error("PROVISIONING_RESULT_INVALID");
+    const expected = `https://chatgpt.com/g/${result.gptId}`;
+    if (result.carrierUrl !== expected)
+        throw new Error("PROVISIONING_RESULT_INVALID");
+    return {
+        status: "LIVE_CREATED",
+        packageName: material.packageName,
+        version: material.version,
+        gptId: result.gptId,
+        carrierUrl: result.carrierUrl,
+    };
+}
+function carrierGptId(carrierUrl) {
+    const url = new URL(carrierUrl);
+    const match = /^\/g\/(g-[A-Za-z0-9_-]+)$/.exec(url.pathname);
+    if (url.origin !== "https://chatgpt.com" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "" ||
+        !match?.[1])
+        throw new Error("PROVISIONING_CARRIER_URL_INVALID");
+    return match[1];
+}
+function authResult(value, carrierUrl) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("PROVISIONING_AUTH_RESULT_INVALID");
+    const result = value;
+    const expectedGptId = carrierGptId(carrierUrl);
+    if (result.status !== "AUTH_UPDATED" || result.gptId !== expectedGptId)
+        throw new Error("PROVISIONING_AUTH_RESULT_INVALID");
+    return { status: "AUTH_UPDATED", gptId: expectedGptId, carrierUrl };
+}
+const sleep = (milliseconds) => new Promise((resolveWait) => setTimeout(resolveWait, milliseconds));
+export async function createCustomGptProvisioningHost(options) {
+    const bridge = await createCustomGptProvisioningBridgeServer(options);
+    const onlineTimeoutMs = options.onlineTimeoutMs ?? 30_000;
+    async function waitUntilOnline() {
+        const deadline = Date.now() + onlineTimeoutMs;
+        while (Date.now() < deadline) {
+            if (bridge.status().online)
+                return;
+            await sleep(100);
+        }
+        throw new Error("PROVISIONING_EXTENSION_OFFLINE");
+    }
+    async function provisionPackage(input) {
+        await waitUntilOnline();
+        if (input.credential !== undefined && input.credential.length < 32)
+            throw new Error("PROVISIONING_ROLE_CREDENTIAL_INVALID");
+        const schemaPath = packageAsset(input.packageRoot, input.material.actionSchema, "ACTION_SCHEMA_PATH");
+        const bundlePath = packageAsset(input.packageRoot, input.material.knowledgeBundle, "KNOWLEDGE_BUNDLE_PATH");
+        const schema = hydratedSchema(await readFile(schemaPath, "utf8"), input.gatewayUrl);
+        const bundle = await materializeCustomGptKnowledgeBundle({
+            bundlePath,
+            stagingRoot: input.stagingRoot,
+        });
+        try {
+            const relayFiles = await bridge.provisioning.registerFiles(bundle.files.map((file) => ({
+                name: file.name,
+                path: file.path,
+                mime: file.mime,
+            })));
+            const request = {
+                ...input.material,
+                actionSchema: schema,
+                ...(input.credential === undefined
+                    ? {}
+                    : { bearerCredential: input.credential }),
+                knowledgeFiles: relayFiles.map(({ name, mime, sizeBytes, sha256, url }) => ({
+                    name,
+                    mime,
+                    sizeBytes,
+                    sha256,
+                    url,
+                })),
+            };
+            if (JSON.stringify(request).length >= 100_000)
+                throw new Error("PROVISIONING_REQUEST_BUDGET_EXCEEDED");
+            const value = await bridge.provisioning.request({
+                type: "PROVISION_CUSTOM_GPT",
+                request,
+            });
+            return {
+                ...liveResult(value, input.material),
+                knowledgeBundleSha256: bundle.bundleSha256,
+                knowledgeFiles: fileEvidence(bundle.files),
+            };
+        }
+        finally {
+            await rm(bundle.stagingDirectory, { recursive: true, force: true });
+        }
+    }
+    async function finalizeRoleAuth(input) {
+        await waitUntilOnline();
+        carrierGptId(input.carrierUrl);
+        if (input.credential.length < 32)
+            throw new Error("PROVISIONING_ROLE_CREDENTIAL_INVALID");
+        let credential = input.credential;
+        try {
+            const value = await bridge.provisioning.request({
+                type: "FINALIZE_CUSTOM_GPT_AUTH",
+                request: { carrierUrl: input.carrierUrl, credential },
+            });
+            return authResult(value, input.carrierUrl);
+        }
+        finally {
+            credential = "";
+        }
+    }
+    return Object.freeze({
+        endpoint: bridge.endpoint,
+        status: bridge.status,
+        provisionPackage,
+        finalizeRoleAuth,
+        close: bridge.close,
+    });
+}
+function sharedFactString(facts, name) {
+    const value = facts?.[name];
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`PROVISIONING_SHARED_FACT_MISSING:${name}`);
+    return value;
+}
+export async function createWorkspaceCustomGptProvisioningHost(input) {
+    const moduleRef = "execution-browser-extension";
+    const facts = await readModuleSharedFacts({ workspaceRoot: input.workspaceRoot }, moduleRef);
+    const extensionId = sharedFactString(facts, "extensionId");
+    if (!/^[a-z]{32}$/.test(extensionId))
+        throw new Error("PROVISIONING_EXTENSION_ID_INVALID");
+    const tokenFile = sharedFactString(facts, "provisioningBridgeTokenFile");
+    const endpointText = sharedFactString(facts, "provisioningBridgeEndpoint");
+    let endpoint;
+    try {
+        endpoint = new URL(endpointText);
+    }
+    catch {
+        throw new Error("PROVISIONING_ENDPOINT_INVALID");
+    }
+    const port = Number(endpoint.port);
+    if (endpoint.protocol !== "http:" ||
+        endpoint.hostname !== "127.0.0.1" ||
+        endpoint.pathname !== "/" ||
+        endpoint.search !== "" ||
+        endpoint.hash !== "" ||
+        !Number.isInteger(port) ||
+        port <= 0 ||
+        port > 65_535)
+        throw new Error("PROVISIONING_ENDPOINT_INVALID");
+    const token = (await readFile(tokenFile, "utf8")).trim();
+    if (token.length < 32)
+        throw new Error("PROVISIONING_TOKEN_INVALID");
+    return createCustomGptProvisioningHost({
+        token,
+        extensionId,
+        host: "127.0.0.1",
+        port,
+        ...(input.commandTimeoutMs === undefined
+            ? {}
+            : { commandTimeoutMs: input.commandTimeoutMs }),
+        ...(input.onlineTimeoutMs === undefined
+            ? {}
+            : { onlineTimeoutMs: input.onlineTimeoutMs }),
+    });
+}

package/dist/src/custom-gpt-role.d.ts

@@ -0,0 +1,66 @@
+import { type CustomGptPackageProvisioningMaterial, type CustomGptProvisioningResult } from "./custom-gpt-provisioner.ts";
+export type CreateCustomGptRoleInput = {
+    workspaceRoot: string;
+    packageRoot: string;
+    stagingRoot: string;
+    gatewayUrl: string;
+    material: CustomGptPackageProvisioningMaterial;
+    commandTimeoutMs?: number;
+    onlineTimeoutMs?: number;
+};
+export type CustomGptRoleRecordInput = {
+    agentPackageRef: string;
+    registeredPackageVersion: string;
+    roleRef: string;
+    carrierUrl: string;
+};
+export type CustomGptRoleRegistryPort = {
+    prepareCredential(): Promise<{
+        credential: string;
+    }> | {
+        credential: string;
+    };
+    saveRole(input: CustomGptRoleRecordInput, preparedCredential: string): Promise<{
+        credential: string;
+        rollback(): Promise<void>;
+    }>;
+    deleteRole(roleRef: string): Promise<void>;
+    inspectRole(input: {
+        agentPackageRef: string;
+        expectedPackageVersion: string;
+    }): {
+        status: string;
+        role?: {
+            roleRef: string;
+            carrierUrl: string;
+        };
+    };
+};
+type CustomGptProvisioningHostPort = {
+    provisionPackage(input: {
+        packageRoot: string;
+        stagingRoot: string;
+        gatewayUrl: string;
+        material: CustomGptPackageProvisioningMaterial;
+        credential: string;
+    }): Promise<CustomGptProvisioningResult>;
+    close(): Promise<void>;
+};
+export type CreateCustomGptRolePorts = {
+    roleRegistry: CustomGptRoleRegistryPort;
+    verifyCarrier(input: {
+        agentPackageRef: string;
+        registeredPackageVersion: string;
+        roleRef: string;
+        carrierUrl: string;
+        gatewayUrl: string;
+        credential: string;
+    }): Promise<void>;
+    createProvisioningHost?: (input: {
+        workspaceRoot: string;
+        commandTimeoutMs?: number;
+        onlineTimeoutMs?: number;
+    }) => Promise<CustomGptProvisioningHostPort>;
+};
+export declare function createCustomGptRole(input: CreateCustomGptRoleInput, ports: CreateCustomGptRolePorts): Promise<CustomGptProvisioningResult>;
+export {};

package/dist/src/custom-gpt-role.js

@@ -0,0 +1,98 @@
+import { resolve } from "node:path";
+import { createWorkspaceCustomGptProvisioningHost, } from "./custom-gpt-provisioner.js";
+const workspaceCreateTails = new Map();
+function enqueueWorkspaceCreate(workspaceRoot, operation) {
+    const key = resolve(workspaceRoot);
+    const previous = workspaceCreateTails.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    const settled = current.then(() => undefined, () => undefined);
+    workspaceCreateTails.set(key, settled);
+    return current.finally(() => {
+        if (workspaceCreateTails.get(key) === settled)
+            workspaceCreateTails.delete(key);
+    });
+}
+function assertLiveCreated(result, material) {
+    if (result.status !== "LIVE_CREATED" ||
+        result.packageName !== material.packageName ||
+        result.version !== material.version ||
+        !/^g-[A-Za-z0-9_-]+$/.test(result.gptId) ||
+        result.carrierUrl !== `https://chatgpt.com/g/${result.gptId}`)
+        throw new Error("LIVE_CREATED_RESULT_INVALID");
+}
+export async function createCustomGptRole(input, ports) {
+    return enqueueWorkspaceCreate(input.workspaceRoot, async () => {
+        const createHost = ports.createProvisioningHost ?? createWorkspaceCustomGptProvisioningHost;
+        const host = await createHost({
+            workspaceRoot: input.workspaceRoot,
+            ...(input.commandTimeoutMs === undefined
+                ? {}
+                : { commandTimeoutMs: input.commandTimeoutMs }),
+            ...(input.onlineTimeoutMs === undefined
+                ? {}
+                : { onlineTimeoutMs: input.onlineTimeoutMs }),
+        });
+        let result;
+        let rollbackSavedRole;
+        let credential = "";
+        try {
+            const prepared = await ports.roleRegistry.prepareCredential();
+            if (typeof prepared.credential !== "string" ||
+                prepared.credential.length < 32)
+                throw new Error("WORKSPACE_ROLE_CREDENTIAL_INVALID");
+            credential = prepared.credential;
+            result = await host.provisionPackage({
+                packageRoot: input.packageRoot,
+                stagingRoot: input.stagingRoot,
+                gatewayUrl: input.gatewayUrl,
+                material: input.material,
+                credential,
+            });
+            assertLiveCreated(result, input.material);
+            const saved = await ports.roleRegistry.saveRole({
+                agentPackageRef: result.packageName,
+                registeredPackageVersion: result.version,
+                roleRef: result.gptId,
+                carrierUrl: result.carrierUrl,
+            }, credential);
+            rollbackSavedRole = saved.rollback;
+            if (typeof saved.credential !== "string" || saved.credential.length < 32)
+                throw new Error("WORKSPACE_ROLE_CREDENTIAL_INVALID");
+            if (saved.credential !== credential)
+                throw new Error("WORKSPACE_ROLE_CREDENTIAL_MISMATCH");
+            credential = saved.credential;
+            const persisted = ports.roleRegistry.inspectRole({
+                agentPackageRef: result.packageName,
+                expectedPackageVersion: result.version,
+            });
+            if (persisted.status !== "READY" ||
+                persisted.role?.roleRef !== result.gptId ||
+                persisted.role.carrierUrl !== result.carrierUrl)
+                throw new Error("WORKSPACE_ROLE_PERSISTENCE_NOT_READY");
+            await ports.verifyCarrier({
+                agentPackageRef: result.packageName,
+                registeredPackageVersion: result.version,
+                roleRef: result.gptId,
+                carrierUrl: result.carrierUrl,
+                gatewayUrl: input.gatewayUrl,
+                credential,
+            });
+            return result;
+        }
+        catch (error) {
+            if (rollbackSavedRole) {
+                try {
+                    await rollbackSavedRole();
+                }
+                catch {
+                    throw new Error("WORKSPACE_ROLE_ROLLBACK_FAILED");
+                }
+            }
+            throw error;
+        }
+        finally {
+            credential = "";
+            await host.close();
+        }
+    });
+}

package/dist/src/install-workflow.d.ts

@@ -0,0 +1,29 @@
+export type BrowserExtensionDesktop = {
+    copyText(value: string): void | Promise<void>;
+    openExtensionsPage(): void | Promise<void>;
+    showInstruction(message: string): void | Promise<void>;
+};
+export type BrowserExtensionPair = (context: {
+    workspaceRoot: string;
+}, options: {
+    timeoutMs?: number;
+    onWaiting?: (input: {
+        loadDir: string;
+        endpoint: string;
+    }) => void | Promise<void>;
+}) => Promise<{
+    extensionId: string;
+    extensionInstanceId: string;
+}>;
+export declare function browserExtensionInstallInstruction(loadDir: string): string;
+export declare function browserExtensionSetupSuccessMessage(): string;
+export declare function browserExtensionSetupFailureMessage(error: unknown): string;
+export declare function runInteractiveBrowserExtensionSetup(input: {
+    workspaceRoot: string;
+    timeoutMs?: number;
+    desktop?: BrowserExtensionDesktop;
+    pair?: BrowserExtensionPair;
+}): Promise<{
+    extensionId: string;
+    extensionInstanceId: string;
+}>;

package/dist/src/install-workflow.js

@@ -0,0 +1,64 @@
+import { spawn, spawnSync } from "node:child_process";
+import { pairBrowserExtensionSetup } from "../deployment/adapter.js";
+export function browserExtensionInstallInstruction(loadDir) {
+    return `\nChrome 浏览器扩展\n\nProFlow 已准备好扩展文件，并已复制安装目录：\n${loadDir}\n\n请在已经打开的 Chrome 扩展管理页完成以下安装操作：\n1. 如果“开发者模式”尚未开启，请开启\n2. 点击“加载未打包的扩展程序”\n3. 在目录选择窗口中粘贴并确认刚刚复制的目录\n\n完成后无需返回输入任何内容。ProFlow 会自动检测扩展并继续。\n`;
+}
+export function browserExtensionSetupSuccessMessage() {
+    return "\n✓ Chrome 浏览器扩展已连接\n✓ 配置与真实 heartbeat 验证通过\n\n浏览器扩展：READY\n";
+}
+export function browserExtensionSetupFailureMessage(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (detail === "PAIRING_TIMEOUT") {
+        return "✕ 暂未检测到浏览器扩展连接\n\n请确认扩展已经在 Chrome 中完成加载。已准备好的扩展文件和机器配置不会丢失。\n下一步：重新执行 platform setup\n错误代码：PAIRING_TIMEOUT\n";
+    }
+    const code = /^[A-Z][A-Z0-9_:-]*$/.test(detail)
+        ? detail
+        : "BROWSER_EXTENSION_SETUP_FAILED";
+    return `✕ 浏览器扩展配置失败\n\n详情：${detail}\n错误代码：${code}\n`;
+}
+function systemDesktop() {
+    return {
+        copyText(value) {
+            const command = process.platform === "darwin"
+                ? "pbcopy"
+                : process.platform === "win32"
+                    ? "clip"
+                    : "xclip";
+            const parameters = process.platform === "linux" ? ["-selection", "clipboard"] : [];
+            spawnSync(command, parameters, { input: value, encoding: "utf8" });
+        },
+        openExtensionsPage() {
+            const url = "chrome://extensions";
+            const command = process.platform === "darwin"
+                ? "open"
+                : process.platform === "win32"
+                    ? "cmd"
+                    : "xdg-open";
+            const parameters = process.platform === "darwin"
+                ? ["-a", "Google Chrome", url]
+                : process.platform === "win32"
+                    ? ["/c", "start", "", url]
+                    : [url];
+            const child = spawn(command, parameters, {
+                detached: true,
+                stdio: "ignore",
+            });
+            child.unref();
+        },
+        showInstruction(message) {
+            process.stdout.write(message);
+        },
+    };
+}
+export async function runInteractiveBrowserExtensionSetup(input) {
+    const desktop = input.desktop ?? systemDesktop();
+    const pair = input.pair ?? pairBrowserExtensionSetup;
+    return pair({ workspaceRoot: input.workspaceRoot }, {
+        timeoutMs: input.timeoutMs ?? 120_000,
+        async onWaiting({ loadDir }) {
+            await desktop.copyText(loadDir);
+            await desktop.openExtensionsPage();
+            await desktop.showInstruction(browserExtensionInstallInstruction(loadDir));
+        },
+    });
+}

package/dist/src/pairing.d.ts

@@ -0,0 +1,20 @@
+export interface BrowserExtensionPairingOptions {
+    token: string;
+    host?: "127.0.0.1";
+    port?: number;
+    pairingTimeoutMs?: number;
+}
+export type BrowserExtensionPairingResult = {
+    extensionId: string;
+    extensionInstanceId: string;
+};
+export declare function createBrowserExtensionPairingServer(options: BrowserExtensionPairingOptions): Promise<Readonly<{
+    endpoint: string;
+    status(): {
+        paired: boolean;
+        extensionId: string | null;
+        extensionInstanceId: string | null;
+    };
+    waitForPairing(): Promise<BrowserExtensionPairingResult>;
+    close(): Promise<void>;
+}>>;

package/dist/src/pairing.js

@@ -0,0 +1,176 @@
+import { timingSafeEqual } from "node:crypto";
+import { createServer, } from "node:http";
+const jsonHeaders = {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+};
+function safeEqual(left, right) {
+    const leftBytes = Buffer.from(left);
+    const rightBytes = Buffer.from(right);
+    return (leftBytes.length === rightBytes.length &&
+        timingSafeEqual(leftBytes, rightBytes));
+}
+function send(response, status, value) {
+    response.writeHead(status, jsonHeaders);
+    response.end(value === undefined ? "" : JSON.stringify(value));
+}
+async function readJson(request) {
+    let body = "";
+    for await (const chunk of request) {
+        body += String(chunk);
+        if (body.length > 10_000)
+            throw new Error("PAIRING_INPUT_INVALID");
+    }
+    const parsed = body.length === 0 ? {} : JSON.parse(body);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("PAIRING_INPUT_INVALID");
+    }
+    return parsed;
+}
+function text(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error("PAIRING_INPUT_INVALID");
+    return value;
+}
+function extensionIdentity(request) {
+    const origin = request.headers.origin;
+    const match = typeof origin === "string"
+        ? /^chrome-extension:\/\/([a-z]{32})$/.exec(origin)
+        : null;
+    if (!match)
+        throw new Error("PAIRING_AUTH_INVALID");
+    return match[1];
+}
+function authenticate(request, token) {
+    const authorization = request.headers.authorization;
+    if (!authorization?.startsWith("Bearer ") ||
+        !safeEqual(authorization.slice(7), token)) {
+        throw new Error("PAIRING_AUTH_INVALID");
+    }
+    return extensionIdentity(request);
+}
+export async function createBrowserExtensionPairingServer(options) {
+    if (options.token.length < 32) {
+        throw new TypeError("pairing token must contain at least 32 characters");
+    }
+    const timeoutMs = options.pairingTimeoutMs ?? 120_000;
+    let identity;
+    let paired;
+    let closed = false;
+    const waiters = new Set();
+    const resolveWaiters = (value) => {
+        for (const waiter of waiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve(value);
+        }
+        waiters.clear();
+    };
+    const rejectWaiters = (error) => {
+        for (const waiter of waiters) {
+            clearTimeout(waiter.timer);
+            waiter.reject(error);
+        }
+        waiters.clear();
+    };
+    const server = createServer(async (request, response) => {
+        try {
+            const originId = extensionIdentity(request);
+            response.setHeader("access-control-allow-origin", `chrome-extension://${originId}`);
+            response.setHeader("vary", "origin");
+            if (request.method === "OPTIONS") {
+                response.setHeader("access-control-allow-headers", "authorization, content-type");
+                response.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+                response.writeHead(204);
+                response.end();
+                return;
+            }
+            authenticate(request, options.token);
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method === "POST" && url.pathname === "/v1/session/hello") {
+                const body = await readJson(request);
+                const extensionId = text(body.extensionId);
+                const extensionInstanceId = text(body.extensionInstanceId);
+                if (extensionId !== originId)
+                    throw new Error("PAIRING_AUTH_INVALID");
+                if (identity && identity.extensionId !== extensionId) {
+                    throw new Error("PAIRING_AUTH_INVALID");
+                }
+                identity = { extensionId, extensionInstanceId };
+                send(response, 200, { accepted: true });
+                return;
+            }
+            if (!identity || originId !== identity.extensionId) {
+                throw new Error("PAIRING_AUTH_INVALID");
+            }
+            if (url.searchParams.get("extensionInstanceId") !==
+                identity.extensionInstanceId) {
+                throw new Error("PAIRING_AUTH_INVALID");
+            }
+            if (request.method === "POST" &&
+                url.pathname === "/v1/session/heartbeat") {
+                paired = { ...identity };
+                resolveWaiters(paired);
+                send(response, 200, { accepted: true });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/v1/commands/next") {
+                send(response, 204);
+                return;
+            }
+            send(response, 404, { error: "NOT_FOUND" });
+        }
+        catch (error) {
+            const code = error instanceof Error ? error.message : "PAIRING_INPUT_INVALID";
+            const status = code === "PAIRING_AUTH_INVALID" ? 401 : 400;
+            send(response, status, { error: code });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("pairing address missing");
+    const endpoint = `http://127.0.0.1:${address.port}`;
+    return Object.freeze({
+        endpoint,
+        status() {
+            return {
+                paired: paired !== undefined,
+                extensionId: identity?.extensionId ?? null,
+                extensionInstanceId: identity?.extensionInstanceId ?? null,
+            };
+        },
+        waitForPairing() {
+            if (paired)
+                return Promise.resolve({ ...paired });
+            if (closed)
+                return Promise.reject(new Error("PAIRING_CLOSED"));
+            return new Promise((resolve, reject) => {
+                const waiter = {
+                    resolve,
+                    reject,
+                    timer: setTimeout(() => {
+                        waiters.delete(waiter);
+                        reject(new Error("PAIRING_TIMEOUT"));
+                    }, timeoutMs),
+                };
+                waiters.add(waiter);
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            rejectWaiters(new Error("PAIRING_CLOSED"));
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+                server.closeAllConnections();
+            });
+        },
+    });
+}