@tomflow/proflow-execution-browser-extension 0.1.2 → 0.1.4

package/CONFIGURATION.md

@@ -0,0 +1,33 @@
+# execution-browser-extension configuration
+
+Canonical public config: `.proflow/config/execution-browser-extension.json`
+
+This file is Workspace-owned data. `platform uninstall` does not delete it. Values are JSON strings. Raw secrets must not be stored here; `secretRef` fields contain opaque references only.
+
+## Fields
+
+| Key | Type | Required | Sensitive | Source | Meaning |
+|---|---|---:|---:|---|---|
+| `bridge.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Browser Reality Bridge endpoint |
+| `bridge.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Browser Reality Bridge extension token |
+| `taskApplication.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Platform Host Task application endpoint |
+| `taskApplication.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Platform Host Task application token |
+| `approvalApplication.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Platform Host Approval application endpoint |
+| `approvalApplication.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Platform Host Approval application token |
+| `verificationEvidenceFile` | `path` | yes | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs |
+| `chromeRuntimeModuleRef` | `moduleRef` | no | no | Another installed ProFlow Module reference selected from `platform docs` / Module topology. | External resource module governing the Chrome runtime |
+| `carrierModuleRef` | `moduleRef` | no | no | Another installed ProFlow Module reference selected from `platform docs` / Module topology. | External resource module governing the Custom GPT carrier |
+
+## Materialize
+
+Create or update the canonical JSON object at:
+
+`.proflow/config/execution-browser-extension.json`
+
+Use only declared keys and string values. Do not create a second Platform configuration database.
+
+The Browser Extension also requires a package-owned physical runtime config artifact. After the canonical Module config is present, run `proflow-execution-browser-extension materialize-config --workspace <path>`. This package-owned command writes the private runtime artifact under `.proflow/deployment/browser-extension/execution-browser-extension/`; `platform start` must not perform this materialization implicitly.
+
+## Base completion check
+
+Run `platform modules`. This Module should no longer report required keys in `missingConfig`. `platform start` performs the authoritative Module-owned validation before starting anything.

package/dist/deployment/adapter.d.ts

@@ -3,7 +3,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             ok: boolean;
             status: string;
         };
@@ -13,7 +13,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             ok: boolean;
             status: string;
         };
@@ -23,12 +23,13 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             ok: boolean;
             status: string;
-            actionRequired: {
-                action: string;
-                description: string;
+            data: {
+                configStatus: "INCOMPLETE" | "INVALID" | "READY";
+                missingConfig?: string[] | undefined;
+                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED" | "UNKNOWN";
             };
         };
         observedEffects: never[];
@@ -37,7 +38,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             ok: boolean;
             status: string;
             checks: {
@@ -52,10 +53,25 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             ok: boolean;
             status: string;
         };
         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>;
+};

package/dist/deployment/adapter.js

@@ -1,3 +1,7 @@
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { observeDeclaredModuleStatus } from "@tomflow/proflow-module-contract";
 import { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
@@ -16,12 +20,9 @@ export const behaviorAdapter = {
     status: () => ({
         result: {
             ...base,
-            ok: false,
-            status: "ACTION_REQUIRED",
-            actionRequired: {
-                action: "verify-real-carrier",
-                description: "Load in real Chrome and collect ChatGPT E3/E4 evidence",
-            },
+            ok: true,
+            status: "SUCCEEDED",
+            data: observeDeclaredModuleStatus(descriptor, undefined, "UNKNOWN"),
         },
         observedEffects: [],
     }),
@@ -45,3 +46,173 @@ export const behaviorAdapter = {
         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;
+}
+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");
+}
+export async function materializeProductionConfig(input) {
+    const required = [
+        "bridge.endpoint",
+        "bridge.token",
+        "taskApplication.endpoint",
+        "taskApplication.token",
+        "approvalApplication.endpoint",
+        "approvalApplication.token",
+    ];
+    for (const key of required) {
+        if (!input.config[key])
+            throw new Error(`missing required browser config ${key}`);
+    }
+    const runtimeConfig = {
+        proflowRuntimeBridge: {
+            endpoint: loopbackEndpoint(input.config["bridge.endpoint"] ?? "", "bridge.endpoint"),
+            token: await credential(input.config["bridge.token"] ?? "", "bridge.token"),
+        },
+        proflowTaskApplication: {
+            endpoint: loopbackEndpoint(input.config["taskApplication.endpoint"] ?? "", "taskApplication.endpoint"),
+            token: await credential(input.config["taskApplication.token"] ?? "", "taskApplication.token"),
+        },
+        proflowApprovalApplication: {
+            endpoint: loopbackEndpoint(input.config["approvalApplication.endpoint"] ?? "", "approvalApplication.endpoint"),
+            token: await credential(input.config["approvalApplication.token"] ?? "", "approvalApplication.token"),
+        },
+    };
+    const sourceRoot = packageRoot();
+    const loadDir = browserExtensionLoadDir(input.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, "extension"), join(loadDir, "extension"), {
+        recursive: true,
+        force: true,
+    });
+    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 };
+}
+async function readBrowserVerificationEvidence(file, expectedLoadDir) {
+    if (!file)
+        return undefined;
+    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;
+    }
+    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,
+    };
+    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;
+        }
+    };
+    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}`,
+                        },
+                    },
+                observedEffects: [],
+            }),
+            status: async () => {
+                const isConfigured = await configured();
+                const evidence = await readBrowserVerificationEvidence(verificationEvidenceFile, loadDir);
+                return {
+                    result: {
+                        ...boundBase,
+                        ok: true,
+                        status: "SUCCEEDED",
+                        data: observeDeclaredModuleStatus(descriptor, input.config, evidence ? "RUNNING" : "STOPPED", isConfigured),
+                    },
+                    observedEffects: evidence
+                        ? ["Observes real Chrome MV3 load evidence"]
+                        : [],
+                };
+            },
+            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"]
+                        : [],
+                };
+            },
+        },
+    };
+}

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.2";
+    readonly moduleVersion: "0.1.4";
     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.";
@@ -41,10 +40,10 @@ export declare const descriptor: {
         readonly description: "Loopback Browser Reality Bridge endpoint";
     }, {
         readonly key: "bridge.token";
-        readonly type: "secretRef";
+        readonly type: "path";
         readonly required: true;
         readonly sensitive: true;
-        readonly description: "Browser Reality Bridge extension token reference";
+        readonly description: "File containing the Browser Reality Bridge extension token";
     }, {
         readonly key: "taskApplication.endpoint";
         readonly type: "url";
@@ -52,10 +51,10 @@ export declare const descriptor: {
         readonly description: "Loopback Platform Host Task application endpoint";
     }, {
         readonly key: "taskApplication.token";
-        readonly type: "secretRef";
+        readonly type: "path";
         readonly required: true;
         readonly sensitive: true;
-        readonly description: "Platform Host Task application token reference";
+        readonly description: "File containing the Platform Host Task application token";
     }, {
         readonly key: "approvalApplication.endpoint";
         readonly type: "url";
@@ -63,10 +62,15 @@ export declare const descriptor: {
         readonly description: "Loopback Platform Host Approval application endpoint";
     }, {
         readonly key: "approvalApplication.token";
-        readonly type: "secretRef";
+        readonly type: "path";
         readonly required: true;
         readonly sensitive: true;
-        readonly description: "Platform Host Approval application token reference";
+        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";
@@ -99,5 +103,9 @@ export declare const descriptor: {
         readonly id: "overview";
         readonly path: "./README.md";
         readonly description: "Package-owned module overview";
+    }, {
+        readonly id: "configuration";
+        readonly path: "./CONFIGURATION.md";
+        readonly description: "Module configuration fields, sources and materialization instructions";
     }];
 };

package/dist/deployment/descriptor.js

@@ -3,23 +3,40 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "execution-browser-extension",
     packageName: "@tomflow/proflow-execution-browser-extension",
-    moduleVersion: "0.1.2",
+    moduleVersion: "0.1.4",
     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" }],
+    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" },
+        {
+            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" },
+        {
+            kind: "runtime",
+            runtime: "browser",
+            versionRange: ">=1",
+        },
         {
             kind: "human",
             action: "Load and verify the unpacked MV3 extension in the real Chrome profile",
@@ -34,10 +51,10 @@ export const descriptor = {
         },
         {
             key: "bridge.token",
-            type: "secretRef",
+            type: "path",
             required: true,
             sensitive: true,
-            description: "Browser Reality Bridge extension token reference",
+            description: "File containing the Browser Reality Bridge extension token",
         },
         {
             key: "taskApplication.endpoint",
@@ -47,10 +64,10 @@ export const descriptor = {
         },
         {
             key: "taskApplication.token",
-            type: "secretRef",
+            type: "path",
             required: true,
             sensitive: true,
-            description: "Platform Host Task application token reference",
+            description: "File containing the Platform Host Task application token",
         },
         {
             key: "approvalApplication.endpoint",
@@ -60,10 +77,16 @@ export const descriptor = {
         },
         {
             key: "approvalApplication.token",
-            type: "secretRef",
+            type: "path",
             required: true,
             sensitive: true,
-            description: "Platform Host Approval application token reference",
+            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",
@@ -105,5 +128,10 @@ export const descriptor = {
             path: "./README.md",
             description: "Package-owned module overview",
         },
+        {
+            id: "configuration",
+            path: "./CONFIGURATION.md",
+            description: "Module configuration fields, sources and materialization instructions",
+        },
     ],
 };