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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-execution-browser-extension
 
+## 0.1.13
+
+### Patch Changes
+
+- Ship the Phase 3 browser, tunnel, model automation, platform readiness, and documentation closure as one verifiable platform snapshot.
+
 ## 0.1.12
 
 ### Patch Changes

package/DOCS.md

@@ -6,13 +6,19 @@ Execution 领域拥有的 Chrome MV3 Extension，负责 Task UI、审批提醒
 
 ## 主要能力
 
-- 提供 New Task 与 Side Panel UI、Task Observer 和 System Observer。
-- 创建、恢复和唤醒 Custom GPT Conversation，稳定观察 workerRef/c-id。
+- 运行期提供 New Task 与 Side Panel UI、Task Observer、System Observer 和 Browser Effect。
+- 运行期创建、恢复和唤醒 Custom GPT Conversation，稳定观察 workerRef/c-id。
+- 部署期通过独立 `/gpts/editor` / `/gpts/editor/*` Provisioning Surface 物化 Custom GPT；该分支不进入 Task/Worker 状态机。
+- 正常创建路径在单一 GPT Editor 会话中完成字段、Action Schema、API Key/Bearer、Knowledge ZIP、模型与 Capabilities 配置，再创建 Private GPT；不在 Create 后重新打开同一 GPT 做 Auth。
+- Knowledge Bundle 在 Mac 侧先做 ZIP traversal/大小/内部类型校验，最终向 GPT Knowledge 上传 `custom-gpt-knowledge.zip` 本体；不把解包后的 `.md` 逐文件作为正常上传物。
+- `FINALIZE_CUSTOM_GPT_AUTH` 只保留为显式 recovery/repair primitive，不属于正常 `createCustomGptRole` Golden Path。
 - 执行 DOM-first 浏览器操作，必要时使用截图与 Vision 辅助观察。
 
 ## 提供的 API 与 Public Contract
 
-- 提供 `execution-browser-executor` Contract，版本 `1.0.0`。
+- 提供 `execution-browser-executor` Contract，版本 `1.0.0`，仅用于运行期 Browser Execution。
+- 提供 `custom-gpt-web-provisioning` Contract，版本 `1.0.0`，仅用于部署期 Custom GPT Web Provisioning。
+- 两条能力只共享 Extension/loopback transport 等底层设施，不共享业务状态机。
 - 通过本地 Bridge 接收 typed Browser operation 并返回 Evidence。
 
 ## 依赖的 Module、Contract 和外部资源
@@ -26,7 +32,9 @@ Execution 领域拥有的 Chrome MV3 Extension，负责 Task UI、审批提醒
 
 ## 使用方式
 
-运行 `pnpm exec -- proflow-execution-browser-extension setup`，加载准备好的目录、登记 Extension ID、Reload 并验证 Bridge。
+运行 `pnpm exec -- proflow-execution-browser-extension setup --workspace <workspace>`。ProFlow 会先准备 unpacked 目录、运行配置和本地 Bridge，并用真实 hello + heartbeat 尝试重验证已有扩展；已有扩展仍在线时不会再次打扰用户。只有未检测到在线扩展时，ProFlow 才把正确目录复制到剪贴板并打开 `chrome://extensions/`，提示用户完成安装操作：如果开发者模式尚未开启则先开启，然后点击“加载未打包的扩展程序”，在目录选择窗口中粘贴并确认目录。完成后无需回终端输入任何标识或状态；扩展身份、session、hello/heartbeat、Browser Executor 配置和 setup evidence 都由机器自动发现、生成并验证。历史 pairing evidence 不能单独代替本次 live revalidation。
+
+若 pairing 等待超时，ProFlow 保留已经准备好的扩展文件和机器配置，不写伪 READY evidence，并输出稳定错误代码 `PAIRING_TIMEOUT`。用户确认 Chrome 已完成加载后重新执行 `platform setup` 即可。Agent setup 随后通过 `custom-gpt-web-provisioning` 使用同一 Extension package 的部署期分支。
 
 ## 职责边界与限制
 

package/SETUP.md

@@ -1,24 +1,20 @@
 # execution-browser-extension Setup
 
-## STEP-EXECUTION-BROWSER-EXTENSION-01 — 准备扩展并打开 Chrome
+## STEP-EXECUTION-BROWSER-EXTENSION-01 — 加载扩展并自动配对
 Responsible: USER
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 01`
-Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 01`
+Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup`
+Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension setup`
 Required inputs: none
-Verify: `pnpm exec -- proflow-execution-browser-extension setup 01`
-Success condition: 扩展目录已生成并可选择。
-
-## STEP-EXECUTION-BROWSER-EXTENSION-02 — 登记 Extension ID 并生成配置
-Responsible: USER
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 02`
-Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>`
-Required inputs: Chrome Extension ID
 Verify: `pnpm exec -- proflow-execution-browser-extension verify`
-Success condition: Extension ID 和运行配置已保存。
+Success condition: 本地 pairing listener 已收到真实 Extension hello + heartbeat，并持久化部署证据。
+
+运行命令后，ProFlow 会先准备 unpacked 目录和所有机器配置，并尝试用真实 hello + heartbeat 重验证已有扩展。若已有扩展仍在线，则无需任何人工操作，setup 直接继续；只有未检测到在线扩展时，ProFlow 才把正确目录复制到剪贴板、打开 `chrome://extensions/` 并提示用户完成安装操作：如果开发者模式尚未开启则先开启，然后点击“加载未打包的扩展程序”，在目录选择窗口中粘贴并确认刚刚复制的目录。完成后无需回终端输入任何内容；扩展身份确认、Bridge 配置、hello/heartbeat 验证和 READY 状态均由 ProFlow 自动完成。历史 `setup.json` / verification evidence 不能单独跳过本次 live revalidation。
+
+若等待超时，已经准备好的扩展文件和机器配置会保留，且不会写入伪 READY evidence。用户只需确认 Chrome 中已经完成扩展加载，然后重新执行 `platform setup`；稳定错误代码为 `PAIRING_TIMEOUT`。
 
-## STEP-EXECUTION-BROWSER-EXTENSION-03 — 验证 Service Worker 与 Bridge
+## STEP-EXECUTION-BROWSER-EXTENSION-02 — 验证部署状态
 Responsible: AI
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 03`
+Interactive executable: `pnpm exec -- proflow-execution-browser-extension verify`
 Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension verify`
 Required inputs: none
 Verify: `pnpm exec -- proflow-execution-browser-extension verify`

package/dist/deployment/adapter.d.ts

@@ -7,6 +7,16 @@ export declare function materializeProductionConfig(input: {
 }): Promise<{
     loadDir: string;
 }>;
+export declare function pairBrowserExtensionSetup(context: ModuleCommandContext, options?: {
+    timeoutMs?: number;
+    onWaiting?: (input: {
+        loadDir: string;
+        endpoint: string;
+    }) => void | Promise<void>;
+}): Promise<{
+    extensionId: string;
+    extensionInstanceId: string;
+}>;
 export declare const behaviorAdapter: {
     readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
@@ -14,7 +24,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: {
                 loadDir: string;
             };
@@ -27,7 +37,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: never[];
     }>;
@@ -37,7 +47,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "RUNNING" | "STOPPED";
@@ -56,7 +66,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "FAILED";
             error: {
@@ -66,70 +76,61 @@ export declare const behaviorAdapter: {
             };
             data: {
                 readonly steps: readonly [{
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-04";
-                    readonly title: "修复扩展配置";
+                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-RECOVER";
+                    readonly title: "重新加载并自动配对扩展";
                     readonly state: "BLOCKED";
                     readonly responsible: "EXTERNAL";
                     readonly execution: {
                         readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup --extension-id <id>";
+                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup";
                     };
                     readonly requiredInputs: readonly [];
                     readonly verify: "pnpm exec -- proflow-execution-browser-extension verify";
                     readonly successCondition: "配置状态变为“已就绪”";
-                    readonly blockedReason: "Extension ID 或生成配置无效";
+                    readonly blockedReason: "真实 Extension heartbeat 未到达或本地 pairing 失败";
                 }];
             };
         };
         observedEffects: never[];
+    } | {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.13";
+        };
+        observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "ACTION_REQUIRED";
             data: {
                 readonly steps: readonly [{
                     readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-01";
-                    readonly title: "准备扩展并打开 Chrome";
-                    readonly description: "生成 unpacked 目录，复制路径并打开扩展管理页。";
+                    readonly title: "加载扩展并自动配对";
+                    readonly description: "准备 unpacked 目录和本地 Bridge，等待 Chrome Extension 的真实 hello + heartbeat。";
                     readonly state: "TODO";
                     readonly responsible: "USER";
                     readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 01";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 01";
+                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup";
+                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup";
                     };
                     readonly requiredInputs: readonly [];
-                    readonly verify: "pnpm exec -- proflow-execution-browser-extension setup 01";
-                    readonly successCondition: "扩展目录已生成并可选择";
-                    readonly humanAction: "启用开发者模式并选择脚本复制的目录。";
-                }, {
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-02";
-                    readonly title: "登记 Extension ID 并生成配置";
-                    readonly description: "保存扩展 ID，生成 Bridge 配置并提示 Reload。";
-                    readonly state: "TODO";
-                    readonly responsible: "USER";
-                    readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 02";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>";
-                    };
-                    readonly requiredInputs: readonly [{
-                        readonly name: "extensionId";
-                        readonly description: "Chrome Extension ID";
-                        readonly sensitive: false;
-                    }];
                     readonly verify: "pnpm exec -- proflow-execution-browser-extension verify";
-                    readonly successCondition: "Extension ID 和运行配置已保存";
-                    readonly humanAction: "复制扩展 ID，并在配置生成后点击 Reload。";
+                    readonly successCondition: "Extension hello + heartbeat 已被本地 pairing listener 验证并持久化";
+                    readonly humanAction: "启用开发者模式并加载脚本准备的 unpacked 目录；其余身份发现与验证自动完成。";
                 }, {
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-03";
-                    readonly title: "验证 Service Worker 与 Bridge";
-                    readonly description: "重新观察扩展后台和本地 Bridge。";
+                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-02";
+                    readonly title: "验证扩展部署状态";
+                    readonly description: "读取 heartbeat 形成的持久化部署证据。";
                     readonly state: "TODO";
                     readonly responsible: "AI";
                     readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 03";
+                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension verify";
                         readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension verify";
                     };
                     readonly requiredInputs: readonly [];
@@ -143,15 +144,6 @@ export declare const behaviorAdapter: {
             };
         };
         observedEffects: never[];
-    } | {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
-        };
-        observedEffects: string[];
     }>;
     readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
@@ -159,7 +151,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: {
                 docs: string;
             };
@@ -172,11 +164,11 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         } | {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "FAILED";
             error: {
@@ -193,7 +185,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: never[];
     }>;

package/dist/deployment/adapter.js

@@ -3,6 +3,7 @@ import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { deterministicLoopbackPort, ensureModuleSecretFile, moduleWorkspaceStateDirectory, readModuleSharedFacts, writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
+import { createBrowserExtensionPairingServer } from "../src/pairing.js";
 import { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
@@ -15,48 +16,27 @@ const setupPlan = {
     steps: [
         {
             id: "STEP-EXECUTION-BROWSER-EXTENSION-01",
-            title: "准备扩展并打开 Chrome",
-            description: "生成 unpacked 目录，复制路径并打开扩展管理页。",
+            title: "加载扩展并自动配对",
+            description: "准备 unpacked 目录和本地 Bridge，等待 Chrome Extension 的真实 hello + heartbeat。",
             state: "TODO",
             responsible: "USER",
             execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 01",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 01",
+                interactive: "pnpm exec -- proflow-execution-browser-extension setup",
+                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup",
             },
             requiredInputs: [],
-            verify: "pnpm exec -- proflow-execution-browser-extension setup 01",
-            successCondition: "扩展目录已生成并可选择",
-            humanAction: "启用开发者模式并选择脚本复制的目录。",
-        },
-        {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-02",
-            title: "登记 Extension ID 并生成配置",
-            description: "保存扩展 ID，生成 Bridge 配置并提示 Reload。",
-            state: "TODO",
-            responsible: "USER",
-            execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 02",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>",
-            },
-            requiredInputs: [
-                {
-                    name: "extensionId",
-                    description: "Chrome Extension ID",
-                    sensitive: false,
-                },
-            ],
             verify: "pnpm exec -- proflow-execution-browser-extension verify",
-            successCondition: "Extension ID 和运行配置已保存",
-            humanAction: "复制扩展 ID，并在配置生成后点击 Reload。",
+            successCondition: "Extension hello + heartbeat 已被本地 pairing listener 验证并持久化",
+            humanAction: "启用开发者模式并加载脚本准备的 unpacked 目录；其余身份发现与验证自动完成。",
         },
         {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-03",
-            title: "验证 Service Worker 与 Bridge",
-            description: "重新观察扩展后台和本地 Bridge。",
+            id: "STEP-EXECUTION-BROWSER-EXTENSION-02",
+            title: "验证扩展部署状态",
+            description: "读取 heartbeat 形成的持久化部署证据。",
             state: "TODO",
             responsible: "AI",
             execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 03",
+                interactive: "pnpm exec -- proflow-execution-browser-extension verify",
                 nonInteractive: "pnpm exec -- proflow-execution-browser-extension verify",
             },
             requiredInputs: [],
@@ -68,18 +48,18 @@ const setupPlan = {
 const blockedSetupPlan = {
     steps: [
         {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-04",
-            title: "修复扩展配置",
+            id: "STEP-EXECUTION-BROWSER-EXTENSION-RECOVER",
+            title: "重新加载并自动配对扩展",
             state: "BLOCKED",
             responsible: "EXTERNAL",
             execution: {
                 interactive: "pnpm exec -- proflow-execution-browser-extension setup",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup --extension-id <id>",
+                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup",
             },
             requiredInputs: [],
             verify: "pnpm exec -- proflow-execution-browser-extension verify",
             successCondition: "配置状态变为“已就绪”",
-            blockedReason: "Extension ID 或生成配置无效",
+            blockedReason: "真实 Extension heartbeat 未到达或本地 pairing 失败",
         },
     ],
 };
@@ -176,7 +156,10 @@ async function readEvidence(context, loadDir) {
             raw.loadDir === loadDir &&
             typeof raw.extensionId === "string" &&
             /^[a-z]{32}$/.test(raw.extensionId) &&
+            typeof raw.extensionInstanceId === "string" &&
+            raw.extensionInstanceId.length > 0 &&
             raw.serviceWorker === "RUNNING" &&
+            raw.evidenceSource === "PAIRING_HEARTBEAT" &&
             typeof raw.observedAt === "string" &&
             !Number.isNaN(Date.parse(raw.observedAt))
             ? raw
@@ -186,28 +169,19 @@ async function readEvidence(context, loadDir) {
         return undefined;
     }
 }
-function input(context) {
-    const value = context.input;
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return {};
-    const extensionId = Reflect.get(value, "extensionId"), serviceWorker = Reflect.get(value, "serviceWorker"), observedAt = Reflect.get(value, "observedAt");
-    return {
-        ...(typeof extensionId === "string" ? { extensionId } : {}),
-        ...(serviceWorker === "RUNNING"
-            ? { serviceWorker: "RUNNING" }
-            : {}),
-        ...(typeof observedAt === "string" ? { observedAt } : {}),
-    };
-}
 async function ownFacts(context) {
     await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
     const loadDir = browserExtensionLoadDir(context.workspaceRoot);
     const bridgeTokenFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "bridge");
     const bridgePort = deterministicLoopbackPort(context, descriptor.moduleRef, "bridge");
+    const provisioningBridgeTokenFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "provisioning");
+    const provisioningBridgePort = deterministicLoopbackPort(context, descriptor.moduleRef, "provisioning");
     const facts = {
         loadDir,
         bridgeTokenFile,
         bridgeEndpoint: `http://127.0.0.1:${bridgePort}`,
+        provisioningBridgeTokenFile,
+        provisioningBridgeEndpoint: `http://127.0.0.1:${provisioningBridgePort}`,
         verificationEvidenceFile: verificationFile(context),
     };
     const setup = await readSetup(context);
@@ -221,7 +195,7 @@ async function ownFacts(context) {
     await writeModuleSharedFacts(context, descriptor.moduleRef, facts);
     return facts;
 }
-async function materialize(context, setup) {
+async function materializeRuntimeConfig(context) {
     const host = await readModuleSharedFacts(context, "platform-host");
     const endpoint = factString(host, "endpoint"), taskTokenFile = factString(host, "taskApplicationTokenFile"), approvalTokenFile = factString(host, "approvalApplicationTokenFile");
     if (!endpoint || !taskTokenFile || !approvalTokenFile)
@@ -230,11 +204,17 @@ async function materialize(context, setup) {
     const loadDir = String(facts.loadDir);
     const bridgeTokenFile = String(facts.bridgeTokenFile);
     const bridgeEndpoint = String(facts.bridgeEndpoint);
-    const runtimeConfig = {
+    const provisioningBridgeTokenFile = String(facts.provisioningBridgeTokenFile);
+    const provisioningBridgeEndpoint = String(facts.provisioningBridgeEndpoint);
+    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify({
         proflowRuntimeBridge: {
             endpoint: bridgeEndpoint,
             token: await credential(bridgeTokenFile),
         },
+        proflowProvisioningBridge: {
+            endpoint: provisioningBridgeEndpoint,
+            token: await credential(provisioningBridgeTokenFile),
+        },
         proflowTaskApplication: {
             endpoint,
             token: await credential(taskTokenFile),
@@ -243,15 +223,91 @@ async function materialize(context, setup) {
             endpoint,
             token: await credential(approvalTokenFile),
         },
+    }, null, 2)}\n`, { mode: 0o600 });
+    return {
+        facts,
+        loadDir,
+        bridgeTokenFile,
+        bridgeEndpoint,
+        provisioningBridgeTokenFile,
+        provisioningBridgeEndpoint,
+        endpoint,
+        taskTokenFile,
     };
-    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { mode: 0o600 });
-    await writeFile(executorConfigFile(context), `${JSON.stringify({ platformHost: { endpoint, tokenFile: taskTokenFile }, bridge: { extensionId: setup.extensionId, tokenFile: bridgeTokenFile, host: "127.0.0.1", port: Number(new URL(bridgeEndpoint).port) } }, null, 2)}\n`, { mode: 0o600 });
+}
+async function materializeExecutorConfig(context, setup, prepared) {
+    const resolved = prepared ?? (await materializeRuntimeConfig(context));
+    await writeFile(executorConfigFile(context), `${JSON.stringify({ platformHost: { endpoint: resolved.endpoint, tokenFile: resolved.taskTokenFile }, bridge: { extensionId: setup.extensionId, tokenFile: resolved.bridgeTokenFile, host: "127.0.0.1", port: Number(new URL(resolved.bridgeEndpoint).port) } }, null, 2)}\n`, { mode: 0o600 });
     await writeModuleSharedFacts(context, descriptor.moduleRef, {
-        ...facts,
+        ...resolved.facts,
         extensionId: setup.extensionId,
         browserExecutorConfigPath: executorConfigFile(context),
     });
 }
+async function materialize(context, setup) {
+    const prepared = await materializeRuntimeConfig(context);
+    await materializeExecutorConfig(context, setup, prepared);
+}
+async function persistPairedBrowserExtension(context, prepared, identity) {
+    const setup = { extensionId: identity.extensionId };
+    await writeFile(setupFile(context), `${JSON.stringify(setup, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await materializeExecutorConfig(context, setup, prepared);
+    const evidence = {
+        contract: "proflow.browser-extension-verification.v1",
+        moduleVersion: descriptor.moduleVersion,
+        loadDir: prepared.loadDir,
+        extensionId: identity.extensionId,
+        extensionInstanceId: identity.extensionInstanceId,
+        serviceWorker: "RUNNING",
+        evidenceSource: "PAIRING_HEARTBEAT",
+        observedAt: new Date().toISOString(),
+    };
+    await writeFile(verificationFile(context), `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
+    return identity;
+}
+export async function pairBrowserExtensionSetup(context, options = {}) {
+    await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+    await installPackage(context);
+    const existingSetup = await readSetup(context);
+    const existingEvidence = await readEvidence(context, browserExtensionLoadDir(context.workspaceRoot));
+    const canRevalidateExisting = Boolean(existingSetup &&
+        existingEvidence &&
+        existingSetup.extensionId === existingEvidence.extensionId);
+    const prepared = await materializeRuntimeConfig(context);
+    const pairing = await createBrowserExtensionPairingServer({
+        token: await credential(prepared.bridgeTokenFile),
+        host: "127.0.0.1",
+        port: Number(new URL(prepared.bridgeEndpoint).port),
+        pairingTimeoutMs: options.timeoutMs ?? 120_000,
+    });
+    try {
+        const pairingPromise = pairing.waitForPairing();
+        if (canRevalidateExisting) {
+            const timeoutMs = options.timeoutMs ?? 120_000;
+            const revalidationGraceMs = Math.min(2_000, Math.max(25, Math.floor(timeoutMs / 4)));
+            const revalidated = await Promise.race([
+                pairingPromise.then((identity) => ({
+                    kind: "PAIRED",
+                    identity,
+                })),
+                new Promise((resolve) => setTimeout(() => resolve({ kind: "WAITING" }), revalidationGraceMs)),
+            ]);
+            if (revalidated.kind === "PAIRED") {
+                return persistPairedBrowserExtension(context, prepared, revalidated.identity);
+            }
+        }
+        await options.onWaiting?.({
+            loadDir: prepared.loadDir,
+            endpoint: pairing.endpoint,
+        });
+        return persistPairedBrowserExtension(context, prepared, await pairingPromise);
+    }
+    finally {
+        await pairing.close();
+    }
+}
 const failed = (code, message, retryable = true) => ({
     ...base,
     ok: false,
@@ -274,7 +330,7 @@ export const behaviorAdapter = {
         const loadDir = browserExtensionLoadDir(context.workspaceRoot);
         const setup = await readSetup(context);
         const evidence = await readEvidence(context, loadDir);
-        const setupReady = Boolean(setup && evidence);
+        const setupReady = Boolean(setup && evidence && setup.extensionId === evidence.extensionId);
         return {
             result: {
                 ...base,
@@ -305,61 +361,27 @@ export const behaviorAdapter = {
     },
     setup: async (context) => {
         await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
-        const supplied = input(context);
-        let setup = await readSetup(context);
-        if (supplied.extensionId) {
-            if (!/^[a-z]{32}$/.test(supplied.extensionId))
+        await installPackage(context);
+        const setup = await readSetup(context);
+        const evidence = await readEvidence(context, browserExtensionLoadDir(context.workspaceRoot));
+        if (setup && evidence && setup.extensionId === evidence.extensionId) {
+            try {
+                await materialize(context, setup);
+            }
+            catch (error) {
                 return {
                     result: {
-                        ...failed("SETUP_FAILED", "extensionId must be a canonical 32-character Chromium extension id", false),
+                        ...failed("SETUP_FAILED", error instanceof Error
+                            ? error.message
+                            : "browser extension config materialization failed"),
                         data: blockedSetupPlan,
                     },
                     observedEffects: [],
                 };
-            setup = { extensionId: supplied.extensionId };
-            await writeFile(setupFile(context), `${JSON.stringify(setup, null, 2)}\n`, { mode: 0o600 });
-        }
-        if (!setup)
-            return {
-                result: {
-                    ...base,
-                    ok: false,
-                    status: "ACTION_REQUIRED",
-                    data: setupPlan,
-                    actionRequired: {
-                        action: "load-unpacked-extension",
-                        description: `Load ${browserExtensionLoadDir(context.workspaceRoot)} in Chrome, copy its extensionId, then run proflow-execution-browser-extension setup --extension-id <id>.`,
-                    },
-                },
-                observedEffects: [],
-            };
-        try {
-            await materialize(context, setup);
-        }
-        catch (error) {
-            return {
-                result: {
-                    ...failed("SETUP_FAILED", error instanceof Error
-                        ? error.message
-                        : "browser extension config materialization failed"),
-                    data: blockedSetupPlan,
-                },
-                observedEffects: [],
-            };
-        }
-        if (supplied.serviceWorker === "RUNNING") {
-            const evidence = {
-                contract: "proflow.browser-extension-verification.v1",
-                moduleVersion: descriptor.moduleVersion,
-                loadDir: browserExtensionLoadDir(context.workspaceRoot),
-                extensionId: setup.extensionId,
-                serviceWorker: "RUNNING",
-                observedAt: supplied.observedAt ?? new Date().toISOString(),
-            };
-            await writeFile(verificationFile(context), `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
+            }
             return {
                 result: base,
-                observedEffects: ["Records real Chrome MV3 load evidence"],
+                observedEffects: ["Uses heartbeat-proven Chrome MV3 pairing evidence"],
             };
         }
         return {
@@ -369,8 +391,8 @@ export const behaviorAdapter = {
                 status: "ACTION_REQUIRED",
                 data: setupPlan,
                 actionRequired: {
-                    action: "reload-and-verify-extension",
-                    description: "Reload the unpacked extension, confirm its MV3 service worker is RUNNING, then rerun proflow-execution-browser-extension setup --extension-id <id>.",
+                    action: "load-unpacked-extension",
+                    description: `Run pnpm exec -- proflow-execution-browser-extension setup --workspace ${context.workspaceRoot}; then enable Developer Mode and load ${browserExtensionLoadDir(context.workspaceRoot)}. The package CLI materializes bootstrap config, discovers the extension and verifies its heartbeat automatically.`,
                 },
             },
             observedEffects: [],

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "execution-browser-extension";
     readonly packageName: "@tomflow/proflow-execution-browser-extension";
-    readonly moduleVersion: "0.1.12";
+    readonly moduleVersion: "0.1.13";
     readonly kind: "browser-extension";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
@@ -14,6 +14,9 @@ export declare const descriptor: {
     readonly provides: readonly [{
         readonly contractRef: "execution-browser-executor";
         readonly version: "1.0.0";
+    }, {
+        readonly contractRef: "custom-gpt-web-provisioning";
+        readonly version: "1.0.0";
     }];
     readonly requires: readonly [{
         readonly contractRef: "execution";