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

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,14 +330,28 @@ export const behaviorAdapter = {
         const loadDir = browserExtensionLoadDir(context.workspaceRoot);
         const setup = await readSetup(context);
         const evidence = await readEvidence(context, loadDir);
+        const setupReady = Boolean(setup && evidence && setup.extensionId === evidence.extensionId);
         return {
             result: {
                 ...base,
                 data: {
-                    setupStatus: setup && evidence
+                    setupStatus: setupReady
                         ? "READY"
                         : "ACTION_REQUIRED",
                     runtimeStatus: evidence ? "RUNNING" : "STOPPED",
+                    ...(setupReady
+                        ? {}
+                        : {
+                            issues: [
+                                {
+                                    scope: "SETUP",
+                                    code: "EXTENSION_LOAD_REQUIRED",
+                                    message: "Chrome 扩展尚未加载或缺少可验证的运行证据",
+                                    relatedModuleRefs: ["chrome-runtime"],
+                                    nextCommand: "platform setup --module execution-browser-extension",
+                                },
+                            ],
+                        }),
                 },
             },
             observedEffects: evidence
@@ -291,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 {
@@ -355,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.11";
+    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";

package/dist/deployment/descriptor.js

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

package/dist/extension/background.js

@@ -13912,6 +13912,7 @@ async function bootstrapManagedRuntimeConfig() {
   if (!isRecord(raw)) return;
   const managed = raw;
   const bridge = parseConfig(managed.proflowRuntimeBridge);
+  const provisioning = parseConfig(managed.proflowProvisioningBridge);
   const task = parseConfig(managed.proflowTaskApplication);
   const approval = parseConfig(managed.proflowApprovalApplication);
   if (!bridge || !task || !approval) {
@@ -13919,6 +13920,7 @@ async function bootstrapManagedRuntimeConfig() {
   }
   await chrome.storage.local.set({
     proflowRuntimeBridge: bridge,
+    ...provisioning ? { proflowProvisioningBridge: provisioning } : {},
     proflowTaskApplication: task,
     proflowApprovalApplication: approval
   });
@@ -13927,6 +13929,10 @@ async function bridgeConfig() {
   const stored = await chrome.storage.local.get("proflowRuntimeBridge");
   return parseConfig(stored.proflowRuntimeBridge);
 }
+async function provisioningBridgeConfig() {
+  const stored = await chrome.storage.local.get("proflowProvisioningBridge");
+  return parseConfig(stored.proflowProvisioningBridge);
+}
 async function taskApplicationConfig() {
   const stored = await chrome.storage.local.get("proflowTaskApplication");
   return parseConfig(stored.proflowTaskApplication);
@@ -14379,6 +14385,68 @@ async function executeCommand(command) {
   }
   throw new Error("BROWSER_PRIMITIVE_UNAVAILABLE");
 }
+function missingProvisioningReceiver(error46) {
+  const message = error46 instanceof Error ? error46.message : String(error46);
+  return message.includes("Could not establish connection") || message.includes("Receiving end does not exist");
+}
+function isEditorUrl(url2) {
+  return url2 === "https://chatgpt.com/gpts/editor" || Boolean(url2?.startsWith("https://chatgpt.com/gpts/editor/"));
+}
+async function provisioningContentCommand(tabId, operation, request) {
+  let receiverReloaded = false;
+  for (let attempt = 0; attempt < 60; attempt += 1) {
+    let response;
+    try {
+      response = await chrome.tabs.sendMessage(tabId, {
+        type: "PROFLOW_PROVISIONING_COMMAND",
+        operation,
+        request
+      });
+    } catch (error46) {
+      if (!receiverReloaded && missingProvisioningReceiver(error46)) {
+        try {
+          const tab = await chrome.tabs.get(tabId);
+          if (tab.status === "complete" && isEditorUrl(tab.url)) {
+            await chrome.tabs.reload(tabId);
+            receiverReloaded = true;
+          }
+        } catch {
+        }
+      }
+      if (attempt === 59) throw error46;
+      await sleep(250);
+      continue;
+    }
+    if (!isRecord(response) || response.ok !== true) {
+      const detail = isRecord(response) && typeof response.error === "string" ? response.error : "PROVISIONING_CONTENT_FAILED";
+      if ((detail === "PROVISIONING_SURFACE_NOT_READY" || detail === "GPT_EDITOR_CONFIGURE_SURFACE_NOT_READY") && attempt < 59) {
+        await sleep(250);
+        continue;
+      }
+      throw new Error(detail);
+    }
+    return response.value;
+  }
+  throw new Error("PROVISIONING_CONTENT_TIMEOUT");
+}
+async function executeProvisioningCommand(command) {
+  if (!isRecord(command.request))
+    throw new Error("PROVISIONING_COMMAND_INVALID");
+  let editorUrl = "https://chatgpt.com/gpts/editor";
+  if (command.type === "FINALIZE_CUSTOM_GPT_AUTH") {
+    const carrierUrl = new URL(text(command.request.carrierUrl, "CARRIER_URL"));
+    const match = /^\/g\/(g-[A-Za-z0-9_-]+)$/.exec(carrierUrl.pathname);
+    if (carrierUrl.origin !== "https://chatgpt.com" || carrierUrl.username !== "" || carrierUrl.password !== "" || carrierUrl.search !== "" || carrierUrl.hash !== "" || !match?.[1])
+      throw new Error("PROVISIONING_CARRIER_URL_INVALID");
+    editorUrl = `https://chatgpt.com/gpts/editor/${match[1]}`;
+  }
+  const tab = await chrome.tabs.create({ url: editorUrl, active: true });
+  return provisioningContentCommand(
+    numeric(tab.id, "TAB_ID"),
+    command.type,
+    command.request
+  );
+}
 async function bridgeFetch(config2, path, init = {}) {
   return fetch(`${config2.endpoint}${path}`, {
     ...init,
@@ -14471,7 +14539,127 @@ async function runBridgeLoop() {
     }
   }
 }
+var provisioningBridgeLoopStarted = false;
+async function runProvisioningBridgeLoop() {
+  if (provisioningBridgeLoopStarted) return;
+  provisioningBridgeLoopStarted = true;
+  while (true) {
+    const config2 = await provisioningBridgeConfig();
+    if (!config2) {
+      await sleep(1e3);
+      continue;
+    }
+    const query = `?extensionInstanceId=${encodeURIComponent(extensionInstanceId)}`;
+    try {
+      const hello = await bridgeFetch(
+        config2,
+        "/v1/provisioning/session/hello",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            extensionId: chrome.runtime.id,
+            extensionInstanceId
+          })
+        }
+      );
+      if (!hello.ok) throw new Error("PROVISIONING_BRIDGE_HELLO_REJECTED");
+      let lastHeartbeatAt = 0;
+      while (true) {
+        if (Date.now() - lastHeartbeatAt >= 5e3) {
+          const heartbeat = await bridgeFetch(
+            config2,
+            `/v1/provisioning/session/heartbeat${query}`,
+            { method: "POST", body: "{}" }
+          );
+          if (!heartbeat.ok)
+            throw new Error("PROVISIONING_BRIDGE_HEARTBEAT_REJECTED");
+          lastHeartbeatAt = Date.now();
+        }
+        const response = await bridgeFetch(
+          config2,
+          `/v1/provisioning/commands/next${query}`
+        );
+        if (response.status === 204) {
+          await sleep(250);
+          continue;
+        }
+        if (!response.ok) throw new Error("PROVISIONING_BRIDGE_POLL_REJECTED");
+        const command = await response.json();
+        const commandHeartbeat = setInterval(() => {
+          void bridgeFetch(
+            config2,
+            `/v1/provisioning/session/heartbeat${query}`,
+            { method: "POST", body: "{}" }
+          ).catch(() => void 0);
+        }, 2e3);
+        let result;
+        try {
+          result = {
+            commandId: command.commandId,
+            ok: true,
+            value: await executeProvisioningCommand(command)
+          };
+        } catch (error46) {
+          result = {
+            commandId: command.commandId,
+            ok: false,
+            error: error46 instanceof Error ? error46.message : "PROVISIONING_EXTENSION_COMMAND_FAILED"
+          };
+        } finally {
+          clearInterval(commandHeartbeat);
+        }
+        const reported = await bridgeFetch(
+          config2,
+          `/v1/provisioning/commands/result${query}`,
+          { method: "POST", body: JSON.stringify(result) }
+        );
+        if (!reported.ok)
+          throw new Error("PROVISIONING_BRIDGE_RESULT_REJECTED");
+      }
+    } catch {
+      await sleep(1e3);
+    }
+  }
+}
+function provisioningRelayBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32768)
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+  return btoa(binary);
+}
 chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === "PROFLOW_PROVISIONING_RELAY_FETCH") {
+    const rawUrl = typeof message.url === "string" ? message.url : "";
+    let parsed;
+    try {
+      parsed = new URL(rawUrl);
+    } catch {
+      sendResponse({ ok: false, error: "KNOWLEDGE_RELAY_URL_INVALID" });
+      return;
+    }
+    if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || !parsed.pathname.startsWith("/v1/provisioning/files/") || parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "") {
+      sendResponse({ ok: false, error: "KNOWLEDGE_RELAY_URL_INVALID" });
+      return;
+    }
+    void fetch(parsed.toString(), { cache: "no-store" }).then(
+      async (response) => {
+        if (!response.ok) {
+          sendResponse({
+            ok: false,
+            error: `KNOWLEDGE_RELAY_FETCH_FAILED:${response.status}`
+          });
+          return;
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        sendResponse({ ok: true, base64: provisioningRelayBase64(bytes) });
+      },
+      (error46) => sendResponse({
+        ok: false,
+        error: error46 instanceof Error ? `KNOWLEDGE_RELAY_FETCH_FAILED:${error46.message}` : "KNOWLEDGE_RELAY_FETCH_FAILED"
+      })
+    );
+    return true;
+  }
   if (message.type === "PROFLOW_CONTENT_OBSERVATION" && message.observation && sender.tab?.id !== void 0 && sender.tab.windowId !== void 0) {
     const observed = {
       ...message.observation,
@@ -14554,6 +14742,7 @@ async function startBackgroundRuntime() {
   await bootstrapManagedRuntimeConfig();
   await persistSnapshot();
   void runBridgeLoop();
+  void runProvisioningBridgeLoop();
   void runObserverRecovery();
 }
 chrome.runtime.onInstalled.addListener(() => {

package/dist/extension/provisioning-content.d.ts

@@ -0,0 +1 @@
+export {};