@tomflow/proflow-execution-browser-extension 0.1.3 → 0.1.5

package/DOCS.md

@@ -0,0 +1,29 @@
+# @tomflow/proflow-execution-browser-extension — Module Docs
+
+Module ref: `execution-browser-extension`  
+Domain: `execution`  
+Kind: `browser-extension`
+
+Execution-owned MV3 Browser executor, evidence provider and browser application surface.
+
+## Standard management surface
+
+`install / uninstall / status / setup / docs / start / stop`
+
+## Provides
+
+- `execution-browser-executor` `1.0.0`
+
+## Requires
+
+- `execution` `>=1.0.0 <2.0.0`
+- `task-orchestration` `>=1.0.0 <2.0.0`
+- `agent-runtime` `>=1.0.0 <2.0.0`
+
+## Public setup inputs
+
+- None. Deterministic/private values and cross-Module shared facts are not public configuration.
+
+## Ownership boundary
+
+Module business APIs and any module-specific extra commands remain package-owned. Platform does not proxy or interpret them. Current human/external preparation is documented in `SETUP.md`.

package/SETUP.md

@@ -0,0 +1,7 @@
+# @tomflow/proflow-execution-browser-extension — Module Setup
+
+After Module.install materializes the deployment directory and deterministic local configuration, load the unpacked extension in Chrome when requested. Confirm the real extension Service Worker is running, then rerun Module.setup so it can re-observe Chrome reality and record evidence. Endpoints, tokens and evidence paths are not user configuration.
+
+## Completion
+
+Setup is complete only when the Module's own `status` reports `setupStatus=READY`. Re-running setup must re-observe reality; it must not resume from a blind historical step index.

package/dist/deployment/adapter.d.ts

@@ -1,76 +1,130 @@
+import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
+export declare function browserExtensionLoadDir(workspaceRoot: string): string;
+export declare function materializeProductionConfig(input: {
+    moduleRef: string;
+    config: Record<string, string>;
+    workspaceRoot: string;
+}): Promise<{
+    loadDir: string;
+}>;
 export declare const behaviorAdapter: {
-    readonly describe: () => {
+    readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.3";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            data: {
+                loadDir: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+    readonly uninstall: (_context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
         };
         observedEffects: never[];
-    };
-    readonly preflight: () => {
+    }>;
+    readonly status: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "execution-browser-extension";
+            moduleVersion: "0.1.5";
+            data: {
+                setupStatus: "ACTION_REQUIRED" | "READY";
+                runtimeStatus: "RUNNING" | "STOPPED";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    readonly setup: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.3";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED";
+                message: string;
+                retryable: boolean;
+            };
         };
         observedEffects: never[];
-    };
-    readonly status: () => {
+    } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.3";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "ACTION_REQUIRED";
             actionRequired: {
                 action: string;
                 description: string;
             };
         };
         observedEffects: never[];
-    };
-    readonly verify: () => {
+    } | {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        };
+        observedEffects: string[];
+    }>;
+    readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.3";
-            ok: boolean;
-            status: string;
-            checks: {
-                id: string;
-                status: string;
-                message: string;
-            }[];
+            moduleVersion: "0.1.5";
+            data: {
+                docs: string;
+                setup: string;
+            };
         };
         observedEffects: never[];
-    };
-    readonly doctor: () => {
+    }>;
+    readonly start: (context: ModuleCommandContext) => Promise<{
         result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        } | {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.3";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED";
+                message: string;
+                retryable: boolean;
+            };
         };
         observedEffects: never[];
-    };
-};
-export declare function browserExtensionLoadDir(workspaceRoot: string): string;
-export declare function materializeProductionConfig(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-}): Promise<{
-    loadDir: string;
-}>;
-export declare function createProductionBinding(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-}): {
-    behaviorAdapter: Record<string, unknown>;
+    }>;
+    readonly stop: (_context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        };
+        observedEffects: never[];
+    }>;
 };

package/dist/deployment/adapter.js

@@ -1,78 +1,46 @@
 import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+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 { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
-export const behaviorAdapter = {
-    describe: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-    preflight: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-    status: () => ({
-        result: {
-            ...base,
-            ok: false,
-            status: "ACTION_REQUIRED",
-            actionRequired: {
-                action: "verify-real-carrier",
-                description: "Load in real Chrome and collect ChatGPT E3/E4 evidence",
-            },
-        },
-        observedEffects: [],
-    }),
-    verify: () => ({
-        result: {
-            ...base,
-            ok: true,
-            status: "SUCCEEDED",
-            checks: [
-                {
-                    id: "extension-package",
-                    status: "PASS",
-                    message: "The MV3 package is structurally verified; real Carrier readiness remains ACTION_REQUIRED in status",
-                },
-            ],
-        },
-        observedEffects: [],
-    }),
-    doctor: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-};
-function loopbackEndpoint(value, key) {
-    const url = new URL(value);
-    if (url.protocol !== "http:" ||
-        url.hostname !== "127.0.0.1" ||
-        url.pathname !== "/" ||
-        url.search !== "" ||
-        url.hash !== "") {
-        throw new Error(`${key} must be a loopback HTTP origin`);
-    }
-    return value.replace(/\/$/, "");
-}
-async function credential(file, key) {
-    const token = (await readFile(file, "utf8")).trim();
-    if (token.length < 32)
-        throw new Error(`${key} must contain at least 32 characters`);
-    return token;
-}
+const factString = (facts, name) => (typeof facts?.[name] === "string" ? String(facts[name]) : undefined);
 function packageRoot() {
     const candidate = dirname(dirname(fileURLToPath(import.meta.url)));
     return basename(candidate) === "dist" ? dirname(candidate) : candidate;
 }
 export function browserExtensionLoadDir(workspaceRoot) {
-    return join(workspaceRoot, ".proflow", "deployment", "browser-extension", "execution-browser-extension");
+    return join(resolve(workspaceRoot), ".proflow", "deployment", "browser-extension", "execution-browser-extension");
+}
+const stateDir = (context) => moduleWorkspaceStateDirectory(context, descriptor.moduleRef);
+const setupFile = (context) => join(stateDir(context), "setup.json");
+const verificationFile = (context) => join(stateDir(context), "verification.json");
+const executorConfigFile = (context) => join(stateDir(context), "browser-executor.json");
+async function credential(file) {
+    const value = (await readFile(file, "utf8")).trim();
+    if (value.length < 32)
+        throw new Error(`credential ${file} is invalid`);
+    return value;
+}
+function loopbackEndpoint(value, name) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" ||
+        url.hostname !== "127.0.0.1" ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash)
+        throw new Error(`${name} must be a loopback HTTP origin`);
+    return value.replace(/\/$/, "");
 }
 export async function materializeProductionConfig(input) {
+    const context = { workspaceRoot: input.workspaceRoot };
+    const loadDir = await installPackage(context);
     const required = [
         "bridge.endpoint",
         "bridge.token",
@@ -81,31 +49,31 @@ export async function materializeProductionConfig(input) {
         "approvalApplication.endpoint",
         "approvalApplication.token",
     ];
-    for (const key of required) {
-        if (!input.config[key])
-            throw new Error(`missing required browser config ${key}`);
-    }
+    for (const name of required)
+        if (!input.config[name])
+            throw new Error(`missing required browser config ${name}`);
     const runtimeConfig = {
         proflowRuntimeBridge: {
             endpoint: loopbackEndpoint(input.config["bridge.endpoint"] ?? "", "bridge.endpoint"),
-            token: await credential(input.config["bridge.token"] ?? "", "bridge.token"),
+            token: await credential(input.config["bridge.token"] ?? ""),
         },
         proflowTaskApplication: {
             endpoint: loopbackEndpoint(input.config["taskApplication.endpoint"] ?? "", "taskApplication.endpoint"),
-            token: await credential(input.config["taskApplication.token"] ?? "", "taskApplication.token"),
+            token: await credential(input.config["taskApplication.token"] ?? ""),
         },
         proflowApprovalApplication: {
             endpoint: loopbackEndpoint(input.config["approvalApplication.endpoint"] ?? "", "approvalApplication.endpoint"),
-            token: await credential(input.config["approvalApplication.token"] ?? "", "approvalApplication.token"),
+            token: await credential(input.config["approvalApplication.token"] ?? ""),
         },
     };
+    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { mode: 0o600 });
+    return { loadDir };
+}
+async function installPackage(context) {
     const sourceRoot = packageRoot();
-    const loadDir = browserExtensionLoadDir(input.workspaceRoot);
+    const loadDir = browserExtensionLoadDir(context.workspaceRoot);
     await mkdir(join(loadDir, "dist"), { recursive: true });
-    await cp(join(sourceRoot, "dist", "extension"), join(loadDir, "dist", "extension"), {
-        recursive: true,
-        force: true,
-    });
+    await cp(join(sourceRoot, "dist", "extension"), join(loadDir, "dist", "extension"), { recursive: true, force: true });
     await cp(join(sourceRoot, "extension"), join(loadDir, "extension"), {
         recursive: true,
         force: true,
@@ -113,112 +81,221 @@ export async function materializeProductionConfig(input) {
     await cp(join(sourceRoot, "manifest.json"), join(loadDir, "manifest.json"), {
         force: true,
     });
-    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    return { loadDir };
+    return loadDir;
 }
-async function readBrowserVerificationEvidence(file, expectedLoadDir) {
-    if (!file)
+async function readSetup(context) {
+    try {
+        const raw = JSON.parse(await readFile(setupFile(context), "utf8"));
+        return typeof raw.extensionId === "string" &&
+            /^[a-z]{32}$/.test(raw.extensionId)
+            ? raw
+            : undefined;
+    }
+    catch {
         return undefined;
+    }
+}
+async function readEvidence(context, loadDir) {
     try {
-        const raw = JSON.parse(await readFile(file, "utf8"));
-        if (raw.contract !== "proflow.browser-extension-verification.v1" ||
-            raw.moduleVersion !== descriptor.moduleVersion ||
-            raw.loadDir !== expectedLoadDir ||
-            typeof raw.extensionId !== "string" ||
-            raw.extensionId.length < 16 ||
-            raw.serviceWorker !== "RUNNING" ||
-            typeof raw.observedAt !== "string" ||
-            Number.isNaN(Date.parse(raw.observedAt)))
-            return undefined;
-        return raw;
+        const raw = JSON.parse(await readFile(verificationFile(context), "utf8"));
+        return raw.contract === "proflow.browser-extension-verification.v1" &&
+            raw.moduleVersion === descriptor.moduleVersion &&
+            raw.loadDir === loadDir &&
+            typeof raw.extensionId === "string" &&
+            /^[a-z]{32}$/.test(raw.extensionId) &&
+            raw.serviceWorker === "RUNNING" &&
+            typeof raw.observedAt === "string" &&
+            !Number.isNaN(Date.parse(raw.observedAt))
+            ? raw
+            : undefined;
     }
     catch {
         return undefined;
     }
 }
-export function createProductionBinding(input) {
-    const loadDir = browserExtensionLoadDir(input.workspaceRoot);
-    const verificationEvidenceFile = input.config.verificationEvidenceFile;
-    const boundBase = {
-        contract: "deployment.result.v1",
-        moduleRef: descriptor.moduleRef,
-        moduleVersion: descriptor.moduleVersion,
+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 } : {}),
     };
-    const configured = async () => {
-        try {
-            const raw = JSON.parse(await readFile(join(loadDir, "runtime-config.json"), "utf8"));
-            return typeof raw === "object" && raw !== null;
-        }
-        catch {
-            return false;
-        }
+}
+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 facts = {
+        loadDir,
+        bridgeTokenFile,
+        bridgeEndpoint: `http://127.0.0.1:${bridgePort}`,
+        verificationEvidenceFile: verificationFile(context),
     };
-    return {
-        behaviorAdapter: {
-            ...behaviorAdapter,
-            preflight: async () => ({
-                result: (await configured())
-                    ? { ...boundBase, ok: true, status: "SUCCEEDED" }
-                    : {
-                        ...boundBase,
-                        ok: false,
-                        status: "ACTION_REQUIRED",
-                        actionRequired: {
-                            action: "configure-browser-extension",
-                            description: `Materialize Browser Extension runtime config before loading ${loadDir}`,
-                        },
+    const setup = await readSetup(context);
+    if (setup)
+        facts.extensionId = setup.extensionId;
+    try {
+        await readFile(executorConfigFile(context), "utf8");
+        facts.browserExecutorConfigPath = executorConfigFile(context);
+    }
+    catch { }
+    await writeModuleSharedFacts(context, descriptor.moduleRef, facts);
+    return facts;
+}
+async function materialize(context, setup) {
+    const host = await readModuleSharedFacts(context, "platform-host");
+    const endpoint = factString(host, "endpoint"), taskTokenFile = factString(host, "taskApplicationTokenFile"), approvalTokenFile = factString(host, "approvalApplicationTokenFile");
+    if (!endpoint || !taskTokenFile || !approvalTokenFile)
+        throw new Error("platform-host application shared facts are unavailable");
+    const facts = await ownFacts(context);
+    const loadDir = String(facts.loadDir);
+    const bridgeTokenFile = String(facts.bridgeTokenFile);
+    const bridgeEndpoint = String(facts.bridgeEndpoint);
+    const runtimeConfig = {
+        proflowRuntimeBridge: {
+            endpoint: bridgeEndpoint,
+            token: await credential(bridgeTokenFile),
+        },
+        proflowTaskApplication: {
+            endpoint,
+            token: await credential(taskTokenFile),
+        },
+        proflowApprovalApplication: {
+            endpoint,
+            token: await credential(approvalTokenFile),
+        },
+    };
+    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 });
+    await writeModuleSharedFacts(context, descriptor.moduleRef, {
+        ...facts,
+        extensionId: setup.extensionId,
+        browserExecutorConfigPath: executorConfigFile(context),
+    });
+}
+const failed = (code, message, retryable = true) => ({
+    ...base,
+    ok: false,
+    status: "FAILED",
+    error: { code, message, retryable },
+});
+export const behaviorAdapter = {
+    install: async (context) => {
+        const loadDir = await installPackage(context);
+        return {
+            result: { ...base, data: { ...(await ownFacts(context)), loadDir } },
+            observedEffects: ["Materialize the unpacked MV3 extension package"],
+        };
+    },
+    uninstall: async (_context) => ({
+        result: base,
+        observedEffects: [],
+    }),
+    status: async (context) => {
+        const loadDir = browserExtensionLoadDir(context.workspaceRoot);
+        const setup = await readSetup(context);
+        const evidence = await readEvidence(context, loadDir);
+        return {
+            result: {
+                ...base,
+                data: {
+                    setupStatus: setup && evidence
+                        ? "READY"
+                        : "ACTION_REQUIRED",
+                    runtimeStatus: evidence ? "RUNNING" : "STOPPED",
+                },
+            },
+            observedEffects: evidence
+                ? ["Observes real Chrome MV3 load evidence"]
+                : [],
+        };
+    },
+    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))
+                return {
+                    result: failed("SETUP_FAILED", "extensionId must be a canonical 32-character Chromium extension id", false),
+                    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",
+                    actionRequired: {
+                        action: "load-unpacked-extension",
+                        description: `Load ${browserExtensionLoadDir(context.workspaceRoot)} in Chrome, copy its extensionId, then rerun Module.setup with extensionId.`,
                     },
+                },
                 observedEffects: [],
-            }),
-            status: async () => ({
-                result: (await configured())
-                    ? {
-                        ...boundBase,
-                        ok: true,
-                        status: "SUCCEEDED",
-                        data: { loadDir, configMaterialized: true },
-                    }
-                    : {
-                        ...boundBase,
-                        ok: false,
-                        status: "ACTION_REQUIRED",
-                        actionRequired: {
-                            action: "configure-browser-extension",
-                            description: "Browser Extension runtime config is not materialized",
-                        },
-                    },
+            };
+        try {
+            await materialize(context, setup);
+        }
+        catch (error) {
+            return {
+                result: failed("SETUP_FAILED", error instanceof Error
+                    ? error.message
+                    : "browser extension config materialization failed"),
                 observedEffects: [],
-            }),
-            verify: async () => {
-                const evidence = await readBrowserVerificationEvidence(verificationEvidenceFile, loadDir);
-                return {
-                    result: (await configured()) && evidence
-                        ? {
-                            ...boundBase,
-                            ok: true,
-                            status: "SUCCEEDED",
-                            checks: [
-                                {
-                                    id: "real-carrier-e3-e4",
-                                    status: "PASS",
-                                    message: `Real Chrome loaded extension ${evidence.extensionId} from ${loadDir} and its MV3 Service Worker was observed running`,
-                                },
-                            ],
-                        }
-                        : {
-                            ...boundBase,
-                            ok: false,
-                            status: "ACTION_REQUIRED",
-                            actionRequired: {
-                                action: "verify-real-chrome-extension",
-                                description: `Load ${loadDir} in real Chrome and write verified evidence to ${verificationEvidenceFile ?? "the configured verificationEvidenceFile"}`,
-                            },
-                        },
-                    observedEffects: evidence
-                        ? ["Observes real Chrome MV3 load evidence"]
-                        : [],
-                };
+            };
+        }
+        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"],
+            };
+        }
+        return {
+            result: {
+                ...base,
+                ok: false,
+                status: "ACTION_REQUIRED",
+                actionRequired: {
+                    action: "reload-and-verify-extension",
+                    description: "Reload the unpacked extension after runtime config materialization, confirm its MV3 service worker is RUNNING, then rerun Module.setup with serviceWorker=RUNNING.",
+                },
             },
-        },
-    };
-}
+            observedEffects: [],
+        };
+    },
+    docs: async (_context) => ({
+        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        observedEffects: [],
+    }),
+    start: async (context) => {
+        const loadDir = browserExtensionLoadDir(context.workspaceRoot);
+        return {
+            result: (await readEvidence(context, loadDir))
+                ? base
+                : failed("START_FAILED", "browser extension setup is not READY"),
+            observedEffects: [],
+        };
+    },
+    stop: async (_context) => ({
+        result: base,
+        observedEffects: [],
+    }),
+};

package/dist/deployment/descriptor.d.ts

@@ -3,11 +3,10 @@ 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.3";
+    readonly moduleVersion: "0.1.5";
     readonly kind: "browser-extension";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
-    readonly installClass: "core";
     readonly identity: {
         readonly domain: "execution";
         readonly summary: "Execution-owned MV3 Browser executor, evidence provider and browser application surface.";
@@ -34,75 +33,14 @@ export declare const descriptor: {
         readonly kind: "human";
         readonly action: "Load and verify the unpacked MV3 extension in the real Chrome profile";
     }];
-    readonly configSlots: readonly [{
-        readonly key: "bridge.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Browser Reality Bridge endpoint";
-    }, {
-        readonly key: "bridge.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Browser Reality Bridge extension token";
-    }, {
-        readonly key: "taskApplication.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Platform Host Task application endpoint";
-    }, {
-        readonly key: "taskApplication.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Platform Host Task application token";
-    }, {
-        readonly key: "approvalApplication.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Platform Host Approval application endpoint";
-    }, {
-        readonly key: "approvalApplication.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Platform Host Approval application token";
-    }, {
-        readonly key: "verificationEvidenceFile";
-        readonly type: "path";
-        readonly required: true;
-        readonly description: "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs";
-    }, {
-        readonly key: "chromeRuntimeModuleRef";
-        readonly type: "moduleRef";
-        readonly required: false;
-        readonly description: "External resource module governing the Chrome runtime";
-        readonly default: "chrome-runtime";
-    }, {
-        readonly key: "carrierModuleRef";
-        readonly type: "moduleRef";
-        readonly required: false;
-        readonly description: "External resource module governing the Custom GPT carrier";
-        readonly default: "chatgpt-carrier";
-    }];
-    readonly lifecycle: {
-        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor"];
-    };
-    readonly verification: {
-        readonly checks: readonly [{
-            readonly id: "real-carrier-e3-e4";
-            readonly description: "Real Chrome and ChatGPT E3/E4 evidence is present";
-            readonly lifecycle: "verify";
-        }];
-    };
+    readonly configSlots: readonly [];
     readonly effects: readonly [{
         readonly kind: "external-resource";
-        readonly description: "Package an MV3 extension that performs Execution-authorized Browser effects";
+        readonly description: "Materialize the unpacked MV3 extension package";
         readonly retention: "preserve";
     }];
-    readonly documentation: readonly [{
-        readonly id: "overview";
-        readonly path: "./README.md";
-        readonly description: "Package-owned module overview";
-    }];
+    readonly documentation: {
+        readonly docs: "DOCS.md";
+        readonly setup: "SETUP.md";
+    };
 };

package/dist/deployment/descriptor.js

@@ -3,113 +3,55 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "execution-browser-extension",
     packageName: "@tomflow/proflow-execution-browser-extension",
-    moduleVersion: "0.1.3",
+    moduleVersion: "0.1.5",
     kind: "browser-extension",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",
-    installClass: "core",
     identity: {
         domain: "execution",
         summary: "Execution-owned MV3 Browser executor, evidence provider and browser application surface.",
     },
-    provides: [{ contractRef: "execution-browser-executor", version: "1.0.0" }],
-    requires: [
-        { contractRef: "execution", versionRange: ">=1.0.0 <2.0.0" },
-        { contractRef: "task-orchestration", versionRange: ">=1.0.0 <2.0.0" },
-        { contractRef: "agent-runtime", versionRange: ">=1.0.0 <2.0.0" },
-    ],
-    requirements: [
-        { kind: "runtime", runtime: "browser", versionRange: ">=1" },
+    provides: [
         {
-            kind: "human",
-            action: "Load and verify the unpacked MV3 extension in the real Chrome profile",
+            contractRef: "execution-browser-executor",
+            version: "1.0.0",
         },
     ],
-    configSlots: [
-        {
-            key: "bridge.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Browser Reality Bridge endpoint",
-        },
-        {
-            key: "bridge.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Browser Reality Bridge extension token",
-        },
-        {
-            key: "taskApplication.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Platform Host Task application endpoint",
-        },
-        {
-            key: "taskApplication.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Platform Host Task application token",
-        },
+    requires: [
         {
-            key: "approvalApplication.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Platform Host Approval application endpoint",
+            contractRef: "execution",
+            versionRange: ">=1.0.0 <2.0.0",
         },
         {
-            key: "approvalApplication.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Platform Host Approval application token",
+            contractRef: "task-orchestration",
+            versionRange: ">=1.0.0 <2.0.0",
         },
         {
-            key: "verificationEvidenceFile",
-            type: "path",
-            required: true,
-            description: "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs",
+            contractRef: "agent-runtime",
+            versionRange: ">=1.0.0 <2.0.0",
         },
+    ],
+    requirements: [
         {
-            key: "chromeRuntimeModuleRef",
-            type: "moduleRef",
-            required: false,
-            description: "External resource module governing the Chrome runtime",
-            default: "chrome-runtime",
+            kind: "runtime",
+            runtime: "browser",
+            versionRange: ">=1",
         },
         {
-            key: "carrierModuleRef",
-            type: "moduleRef",
-            required: false,
-            description: "External resource module governing the Custom GPT carrier",
-            default: "chatgpt-carrier",
+            kind: "human",
+            action: "Load and verify the unpacked MV3 extension in the real Chrome profile",
         },
     ],
-    lifecycle: {
-        supported: ["describe", "preflight", "status", "verify", "doctor"],
-    },
-    verification: {
-        checks: [
-            {
-                id: "real-carrier-e3-e4",
-                description: "Real Chrome and ChatGPT E3/E4 evidence is present",
-                lifecycle: "verify",
-            },
-        ],
-    },
+    configSlots: [],
     effects: [
         {
             kind: "external-resource",
-            description: "Package an MV3 extension that performs Execution-authorized Browser effects",
+            description: "Materialize the unpacked MV3 extension package",
             retention: "preserve",
         },
     ],
-    documentation: [
-        {
-            id: "overview",
-            path: "./README.md",
-            description: "Package-owned module overview",
-        },
-    ],
+    documentation: {
+        docs: "DOCS.md",
+        setup: "SETUP.md",
+    },
 };

package/dist/src/configure.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function materializeBrowserExtensionConfig(workspaceRoot: string): Promise<{
+    loadDir: string;
+}>;

package/dist/src/configure.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { materializeProductionConfig } from "../deployment/adapter.js";
+function workspaceFromArgs(args) {
+    if (args[0] !== "materialize-config") {
+        throw new Error("Usage: proflow-execution-browser-extension materialize-config [--workspace /absolute/path]");
+    }
+    const workspaceIndex = args.indexOf("--workspace");
+    if (workspaceIndex < 0)
+        return process.cwd();
+    const value = args[workspaceIndex + 1];
+    if (!value || args.length !== 3) {
+        throw new Error("Usage: proflow-execution-browser-extension materialize-config [--workspace /absolute/path]");
+    }
+    return resolve(value);
+}
+export async function materializeBrowserExtensionConfig(workspaceRoot) {
+    const configPath = resolve(workspaceRoot, ".proflow", "config", "execution-browser-extension.json");
+    const parsed = JSON.parse(await readFile(configPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("execution-browser-extension config must be a JSON object");
+    }
+    const config = Object.fromEntries(Object.entries(parsed).map(([key, value]) => {
+        if (typeof value !== "string") {
+            throw new Error(`browser extension config ${key} must be a string`);
+        }
+        return [key, value];
+    }));
+    return materializeProductionConfig({
+        moduleRef: "execution-browser-extension",
+        config,
+        workspaceRoot,
+    });
+}
+async function main() {
+    const workspaceRoot = workspaceFromArgs(process.argv.slice(2));
+    const result = await materializeBrowserExtensionConfig(workspaceRoot);
+    process.stdout.write(`${JSON.stringify({ status: "MATERIALIZED", ...result })}\n`);
+}
+if (import.meta.main)
+    await main();

package/manifest.json

@@ -1,7 +1,7 @@
 {
 	"manifest_version": 3,
 	"name": "ProFlow Execution Browser",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"permissions": ["tabs", "storage", "sidePanel"],
 	"host_permissions": ["https://chatgpt.com/*", "http://127.0.0.1/*"],
 	"background": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-execution-browser-extension",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Execution-owned MV3 Browser executor, evidence provider and browser application surface.",
   "type": "module",
   "publishConfig": {
@@ -11,7 +11,8 @@
     "./bridge": "./dist/src/bridge.js",
     "./deployment/adapter": "./dist/deployment/adapter.js",
     "./deployment/descriptor": "./dist/deployment/descriptor.js",
-    "./runtime-composition": "./dist/src/runtime-composition.js"
+    "./runtime-composition": "./dist/src/runtime-composition.js",
+    "./configure": "./dist/src/configure.js"
   },
   "files": [
     "dist",
@@ -21,15 +22,16 @@
     "proflow.module.json",
     "conformance.json",
     "README.md",
-    "self-install.mjs"
+    "DOCS.md",
+    "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-execution-contracts": "^0.1.2"
+    "@tomflow/proflow-execution-contracts": "^0.1.4",
+    "@tomflow/proflow-module-contract": "^0.1.4"
   },
   "devDependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.1",
-    "@tomflow/proflow-deployment-conformance": "^0.1.2",
-    "@tomflow/proflow-execution-runtime": "^0.1.2"
+    "@tomflow/proflow-execution-runtime": "^0.1.7",
+    "@tomflow/proflow-deployment-conformance": "^0.1.4"
   },
   "keywords": [
     "proflow",
@@ -38,20 +40,11 @@
   ],
   "proflow": {
     "module": true,
-    "installClass": "core",
-    "installRequires": [
-      "@tomflow/proflow-agent-runtime",
-      "@tomflow/proflow-chatgpt-carrier",
-      "@tomflow/proflow-chrome-runtime",
-      "@tomflow/proflow-execution-contracts",
-      "@tomflow/proflow-execution-runtime",
-      "@tomflow/proflow-task-orchestration"
-    ],
     "descriptor": "./dist/deployment/descriptor.js",
     "manifest": "./proflow.module.json"
   },
   "bin": {
-    "proflow-execution-browser-extension": "./self-install.mjs"
+    "proflow-execution-browser-extension": "./dist/src/configure.js"
   },
   "scripts": {
     "test": "node --test tests/**/*.test.ts",

package/proflow.module.json

@@ -3,11 +3,10 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "execution-browser-extension",
 	"packageName": "@tomflow/proflow-execution-browser-extension",
-	"moduleVersion": "0.1.3",
+	"moduleVersion": "0.1.5",
 	"kind": "browser-extension",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
-	"installClass": "core",
 	"identity": {
 		"domain": "execution",
 		"summary": "Execution-owned MV3 Browser executor, evidence provider and browser application surface."
@@ -43,91 +42,16 @@
 			"action": "Load and verify the unpacked MV3 extension in the real Chrome profile"
 		}
 	],
-	"configSlots": [
-		{
-			"key": "bridge.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Browser Reality Bridge endpoint"
-		},
-		{
-			"key": "bridge.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Browser Reality Bridge extension token"
-		},
-		{
-			"key": "taskApplication.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Platform Host Task application endpoint"
-		},
-		{
-			"key": "taskApplication.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Platform Host Task application token"
-		},
-		{
-			"key": "approvalApplication.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Platform Host Approval application endpoint"
-		},
-		{
-			"key": "approvalApplication.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Platform Host Approval application token"
-		},
-		{
-			"key": "verificationEvidenceFile",
-			"type": "path",
-			"required": true,
-			"description": "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs"
-		},
-		{
-			"key": "chromeRuntimeModuleRef",
-			"type": "moduleRef",
-			"required": false,
-			"description": "External resource module governing the Chrome runtime",
-			"default": "chrome-runtime"
-		},
-		{
-			"key": "carrierModuleRef",
-			"type": "moduleRef",
-			"required": false,
-			"description": "External resource module governing the Custom GPT carrier",
-			"default": "chatgpt-carrier"
-		}
-	],
-	"lifecycle": {
-		"supported": ["describe", "preflight", "status", "verify", "doctor"]
-	},
-	"verification": {
-		"checks": [
-			{
-				"id": "real-carrier-e3-e4",
-				"description": "Real Chrome and ChatGPT E3/E4 evidence is present",
-				"lifecycle": "verify"
-			}
-		]
-	},
+	"configSlots": [],
 	"effects": [
 		{
 			"kind": "external-resource",
-			"description": "Package an MV3 extension that performs Execution-authorized Browser effects",
+			"description": "Materialize the unpacked MV3 extension package",
 			"retention": "preserve"
 		}
 	],
-	"documentation": [
-		{
-			"id": "overview",
-			"path": "./README.md",
-			"description": "Package-owned module overview"
-		}
-	]
+	"documentation": {
+		"docs": "DOCS.md",
+		"setup": "SETUP.md"
+	}
 }

package/CHANGELOG.md

@@ -1,19 +0,0 @@
-# @tomflow/proflow-execution-browser-extension
-
-## 0.1.3
-
-### Patch Changes
-
-- Real-1 final remediation and black-box release closure
-
-## 0.1.2
-
-### Patch Changes
-
-- Close the Real-1 global Platform control-plane contract across every published ProFlow package. Platform CLI now owns one durable global Workspace binding with canonical identity, cross-process operation locking, cwd/`--workspace` install targeting, cross-directory instance commands, whole-instance uninstall/rebind, and deterministic npm/yarn/pnpm Workspace package-manager selection. Every package-owned install entry, including newly generated Module Template packages, delegates to the Shell-global `platform` command and fails closed when that global CLI is unavailable; Deployment Conformance and the formal test plans mechanically enforce the same rule across all 24 packages.
-
-## 0.1.1
-
-### Patch Changes
-
-- Close Real-1 deployment graph and Fresh Workspace bootstrap gaps: remove Contract-library runtime-provider aliases, correct Execution/Model dependency direction, materialize logical/moduleRef providers through `installRequires`, enforce repository graph validation, and keep self-install executables stable without package-manager worktree mutation.

package/self-install.mjs

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-
-const [command, ...rest] = process.argv.slice(2);
-const usage =
-	"Usage: npx @tomflow/proflow-execution-browser-extension install\n";
-if (command === "--help" || command === "-h") {
-	process.stdout.write(usage);
-	process.exit(0);
-}
-if (command !== "install" || rest.length > 0) {
-	process.stderr.write(usage);
-	process.exit(2);
-}
-const executable = process.platform === "win32" ? "platform.cmd" : "platform";
-const result = spawnSync(
-	executable,
-	[
-		"install",
-		"@tomflow/proflow-execution-browser-extension",
-		"--workspace",
-		process.cwd(),
-	],
-	{ cwd: process.cwd(), env: process.env, stdio: "inherit" },
-);
-if (result.error) {
-	if (result.error.code === "ENOENT") {
-		process.stderr.write(
-			"GLOBAL_PLATFORM_CLI_REQUIRED: install @tomflow/proflow-platform-cli globally before package-owned install\n",
-		);
-		process.exit(127);
-	}
-	throw result.error;
-}
-process.exit(result.status ?? 1);