@tomflow/proflow-platform-host 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @tomflow/proflow-platform-host
+
+## 0.1.7
+
+### Patch Changes
+
+- Align all Modules to the seven-command setup contract with executable package-owned setup guidance and full Platform setup aggregation.

package/DOCS.md

@@ -0,0 +1,30 @@
+# @tomflow/proflow-platform-host — Module Docs
+
+Module ref: `platform-host`  
+Domain: `platform-architecture`  
+Kind: `service`
+
+Provides the ProFlow local application composition root that binds Task, Agent, Execution and Model owner transports.
+
+## Standard management surface
+
+`install / uninstall / status / setup / docs / start / stop`
+
+## Provides
+
+- `platform-host` `1.0.0`
+
+## Requires
+
+- `task-orchestration` `>=1.0.0 <2.0.0`
+- `agent-runtime` `>=1.0.0 <2.0.0`
+- `execution` `>=1.0.0 <2.0.0`
+- `model-inference` `>=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,19 @@
+# @tomflow/proflow-platform-host — Module Setup
+
+## Goal
+
+Reach `setupStatus=READY` without user configuration.
+
+## Step 1 — Complete machine-owned preparation
+
+**Type:** automatic
+**Executable:** `platform install`
+**What happens:** No user input is required. Local endpoints, stateRoot and credential files are deterministic. Execution/Model facts must come from producer-owned shared facts; if absent this Module reports FAILED rather than asking the user to copy them.
+
+## Step 2 — Re-observe dependency and setup state
+
+**Type:** automatic verification
+**Verify:** `platform status`
+**Success condition:** `platform-host.setupStatus=READY`.
+
+There is no human setup action. A missing machine-owned artifact or producer-owned dependency is a `FAILED` condition to fix in the owning package/dependency; it must never be converted into a request for path/token/endpoint input.

package/dist/deployment/adapter.d.ts

@@ -1,362 +1,138 @@
-type PlatformHostService = {
-    start(): Promise<{
-        host: string;
-        port: number;
-    }>;
-    stop(): Promise<void>;
-    restart(): Promise<{
-        host: string;
-        port: number;
-    }>;
-    status(): Promise<{
-        readiness: "READY" | "NOT_READY";
-    }>;
-};
-export declare function createBehaviorAdapter(service?: PlatformHostService, config?: Record<string, string>, configValid?: boolean): {
-    describe: () => {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: never[];
-    };
-    preflight: () => {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: never[];
-    };
-    status: () => Promise<{
+import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
+export declare const behaviorAdapter: {
+    readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
+            moduleVersion: "0.1.7";
             data: {
-                configStatus: "INCOMPLETE" | "INVALID" | "READY";
-                missingConfig?: string[] | undefined;
-                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED" | "UNKNOWN";
-            };
-        };
-        observedEffects: never[];
-    }>;
-    verify: () => Promise<{
-        result: {
-            contract: "deployment.result.v1";
-            ok: true;
-            status: "SUCCEEDED";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
-                message: string;
-            }[];
-        } | {
-            contract: "deployment.result.v1";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            ok: false;
-            status: "ACTION_REQUIRED";
-            actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
-                message: string;
-            }[];
-        } | {
-            contract: "deployment.result.v1";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            ok: false;
-            status: "ACTION_REQUIRED";
-            actionRequired: {
-                action: string;
-                description: string;
+                endpoint: string;
+                stateRoot: string;
+                identityTokenFile: string;
+                taskApplicationTokenFile: string;
+                approvalApplicationTokenFile: string;
+                gatewayTransportCredentialFile: string;
             };
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
-                message: string;
-            }[];
         };
         observedEffects: never[];
     }>;
-    doctor: () => {
+    readonly uninstall: (context: ModuleCommandContext) => Promise<{
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
+            readonly moduleVersion: "0.1.7";
         };
-        observedEffects: never[];
-    };
-    start: () => Promise<{
+        observedEffects: string[];
+    }>;
+    readonly status: (context: ModuleCommandContext) => Promise<{
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-        } | {
             contract: "deployment.result.v1";
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
+            moduleVersion: "0.1.7";
             data: {
-                host: string;
-                port: number;
+                setupStatus: "FAILED" | "READY";
+                runtimeStatus: "RUNNING" | "STOPPED";
             };
         };
-        observedEffects: string[];
+        observedEffects: never[];
     }>;
-    stop: () => Promise<{
+    readonly setup: (context: ModuleCommandContext) => Promise<{
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
+            readonly moduleVersion: "0.1.7";
         } | {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
+            contract: "deployment.result.v1";
+            moduleRef: "platform-host";
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED" | "STOP_FAILED";
+                message: string;
+                retryable: boolean;
             };
         };
-        observedEffects: string[];
+        observedEffects: never[];
     }>;
-    restart: () => Promise<{
+    readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-        } | {
             contract: "deployment.result.v1";
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
+            moduleVersion: "0.1.7";
             data: {
-                host: string;
-                port: number;
+                docs: string;
+                setup: string;
             };
         };
-        observedEffects: string[];
-    }>;
-    uninstall: () => Promise<{
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: string[];
-    }>;
-};
-export declare const behaviorAdapter: {
-    describe: () => {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
         observedEffects: never[];
-    };
-    preflight: () => {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: never[];
-    };
-    status: () => Promise<{
+    }>;
+    readonly start: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
+            moduleVersion: "0.1.7";
             data: {
-                configStatus: "INCOMPLETE" | "INVALID" | "READY";
-                missingConfig?: string[] | undefined;
-                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED" | "UNKNOWN";
+                host: string;
+                port: number;
             };
         };
-        observedEffects: never[];
-    }>;
-    verify: () => Promise<{
+        observedEffects: string[];
+    } | {
         result: {
-            contract: "deployment.result.v1";
-            ok: true;
-            status: "SUCCEEDED";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
-                message: string;
-            }[];
-        } | {
             contract: "deployment.result.v1";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
+            moduleVersion: "0.1.7";
             ok: false;
-            status: "ACTION_REQUIRED";
-            actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED" | "STOP_FAILED";
                 message: string;
-            }[];
-        } | {
-            contract: "deployment.result.v1";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            ok: false;
-            status: "ACTION_REQUIRED";
-            actionRequired: {
-                action: string;
-                description: string;
+                retryable: boolean;
             };
-            checks: {
-                id: string;
-                status: "FAIL" | "PASS";
-                message: string;
-            }[];
         };
         observedEffects: never[];
     }>;
-    doctor: () => {
+    readonly stop: (context: ModuleCommandContext) => Promise<{
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: never[];
-    };
-    start: () => Promise<{
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-        } | {
-            contract: "deployment.result.v1";
-            ok: true;
-            status: "SUCCEEDED";
-            moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            data: {
-                host: string;
-                port: number;
-            };
+            readonly moduleVersion: "0.1.7";
         };
         observedEffects: string[];
-    }>;
-    stop: () => Promise<{
+    } | {
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        } | {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
-        };
-        observedEffects: string[];
-    }>;
-    restart: () => Promise<{
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-            readonly ok: false;
-            readonly status: "ACTION_REQUIRED";
-            readonly actionRequired: {
-                readonly action: "compose-platform-host";
-                readonly description: "Provide validated Host configuration and owner transports";
-            };
+            readonly moduleVersion: "0.1.7";
         } | {
             contract: "deployment.result.v1";
-            ok: true;
-            status: "SUCCEEDED";
             moduleRef: "platform-host";
-            moduleVersion: "0.1.5";
-            data: {
-                host: string;
-                port: number;
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED" | "STOP_FAILED";
+                message: string;
+                retryable: boolean;
             };
         };
-        observedEffects: string[];
-    }>;
-    uninstall: () => Promise<{
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "platform-host";
-            readonly moduleVersion: "0.1.5";
-        };
-        observedEffects: string[];
+        observedEffects: never[];
     }>;
 };
-export declare function createProductionBinding(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    configByModuleRef: ReadonlyMap<string, Record<string, string>>;
-}): Promise<{
-    behaviorAdapter: Record<string, unknown>;
-}>;
-export {};

package/dist/deployment/adapter.js

@@ -1,5 +1,10 @@
-import { observeDeclaredModuleStatus } from "@tomflow/proflow-module-contract";
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { deterministicLoopbackPort, ensureModuleSecretFile, readModuleSharedFacts, writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
 import { descriptor } from "./descriptor.js";
+const services = new Map();
 const base = {
     contract: "deployment.result.v1",
     ok: true,
@@ -7,155 +12,168 @@ const base = {
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
-const unbound = {
+const key = (context) => resolve(context.workspaceRoot);
+const stateRoot = (context) => join(key(context), ".proflow");
+const factString = (facts, name) => (typeof facts?.[name] === "string" ? String(facts[name]) : undefined);
+async function ensureSecret(path) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    if (!existsSync(path))
+        await writeFile(path, `${randomBytes(32).toString("base64url")}\n`, {
+            mode: 0o600,
+        });
+    await chmod(path, 0o600);
+    const value = (await readFile(path, "utf8")).trim();
+    if (value.length < 32)
+        throw new Error(`invalid private credential ${path}`);
+    return path;
+}
+async function ownFacts(context) {
+    const root = stateRoot(context);
+    const endpoint = `http://127.0.0.1:${deterministicLoopbackPort(context, descriptor.moduleRef)}`;
+    const identityTokenFile = await ensureSecret(join(root, "execution", "secrets", "execution-identity.token"));
+    const taskApplicationTokenFile = await ensureSecret(join(root, "browser", "secrets", "task-application.token"));
+    const approvalApplicationTokenFile = await ensureSecret(join(root, "browser", "secrets", "approval-application.token"));
+    const gatewayTransportCredentialFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "gateway-transport");
+    const facts = {
+        endpoint,
+        stateRoot: root,
+        identityTokenFile,
+        taskApplicationTokenFile,
+        approvalApplicationTokenFile,
+        gatewayTransportCredentialFile,
+    };
+    await writeModuleSharedFacts(context, descriptor.moduleRef, facts);
+    return facts;
+}
+async function dependencies(context) {
+    const execution = await readModuleSharedFacts(context, "execution-runtime");
+    const model = await readModuleSharedFacts(context, "model-runtime");
+    const executionBaseUrl = factString(execution, "endpoint");
+    const executionTransportCredentialFile = factString(execution, "transportCredentialFile");
+    const modelBaseUrl = factString(model, "endpoint");
+    const modelTransportCredentialFile = factString(model, "transportCredentialFile");
+    return executionBaseUrl &&
+        executionTransportCredentialFile &&
+        modelBaseUrl &&
+        modelTransportCredentialFile
+        ? {
+            executionBaseUrl,
+            executionTransportCredentialFile,
+            modelBaseUrl,
+            modelTransportCredentialFile,
+        }
+        : undefined;
+}
+async function running(context) {
+    const { endpoint } = await ownFacts(context);
+    try {
+        return (await fetch(`${endpoint}/ready`, { signal: AbortSignal.timeout(500) })).ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function compose(context) {
+    const own = await ownFacts(context);
+    const deps = await dependencies(context);
+    if (!deps)
+        throw new Error("required Execution/Model shared facts are unavailable");
+    const { createPlatformHost, parsePlatformHostConfig } = await import("../src/index.js");
+    const url = new URL(own.endpoint);
+    const host = createPlatformHost({
+        config: parsePlatformHostConfig({
+            stateRoot: own.stateRoot,
+            workspaceRoot: key(context),
+            host: url.hostname,
+            port: Number(url.port),
+            executionBaseUrl: deps.executionBaseUrl,
+            executionTransportCredentialFile: deps.executionTransportCredentialFile,
+            modelBaseUrl: deps.modelBaseUrl,
+            modelTransportCredentialFile: deps.modelTransportCredentialFile,
+            gatewayTransportCredentialFile: own.gatewayTransportCredentialFile,
+            roles: [],
+        }),
+    });
+    return { start: () => host.start(), stop: () => host.stop() };
+}
+const failed = (code, message) => ({
     ...base,
     ok: false,
-    status: "ACTION_REQUIRED",
-    actionRequired: {
-        action: "compose-platform-host",
-        description: "Provide validated Host configuration and owner transports",
+    status: "FAILED",
+    error: { code, message, retryable: true },
+});
+export const behaviorAdapter = {
+    install: async (context) => ({
+        result: { ...base, data: await ownFacts(context) },
+        observedEffects: [],
+    }),
+    uninstall: async (context) => {
+        const service = services.get(key(context));
+        if (service) {
+            await service.stop();
+            services.delete(key(context));
+        }
+        return {
+            result: base,
+            observedEffects: service ? ["Manage the platform-host process"] : [],
+        };
     },
-};
-export function createBehaviorAdapter(service, config, configValid = true) {
-    return {
-        describe: () => ({ result: base, observedEffects: [] }),
-        preflight: () => ({ result: base, observedEffects: [] }),
-        status: async () => {
-            const status = service ? await service.status() : undefined;
-            const ready = status?.readiness === "READY";
-            const data = observeDeclaredModuleStatus(descriptor, config, ready ? "RUNNING" : service ? "FAILED" : "UNKNOWN", configValid);
+    status: async (context) => ({
+        result: {
+            ...base,
+            data: {
+                setupStatus: (await dependencies(context))
+                    ? "READY"
+                    : "FAILED",
+                runtimeStatus: (await running(context))
+                    ? "RUNNING"
+                    : "STOPPED",
+            },
+        },
+        observedEffects: [],
+    }),
+    setup: async (context) => ({
+        result: (await dependencies(context))
+            ? base
+            : failed("SETUP_FAILED", "required Execution/Model producer shared facts are unavailable"),
+        observedEffects: [],
+    }),
+    docs: async (_context) => ({
+        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        observedEffects: [],
+    }),
+    start: async (context) => {
+        try {
+            const service = await compose(context);
+            const data = await service.start();
+            services.set(key(context), service);
             return {
                 result: { ...base, data },
-                observedEffects: [],
+                observedEffects: ["Manage the platform-host process"],
             };
-        },
-        verify: async () => {
-            const status = service ? await service.status() : undefined;
-            const ready = status?.readiness === "READY";
+        }
+        catch (error) {
             return {
-                result: {
-                    ...(service && ready
-                        ? base
-                        : service
-                            ? {
-                                ...base,
-                                ok: false,
-                                status: "ACTION_REQUIRED",
-                                actionRequired: {
-                                    action: "repair-platform-host",
-                                    description: "Platform Host is not READY",
-                                },
-                            }
-                            : unbound),
-                    checks: [
-                        {
-                            id: "platform-host-readiness",
-                            status: ready ? "PASS" : "FAIL",
-                            message: service
-                                ? `Platform Host readiness is ${status?.readiness ?? "NOT_READY"}`
-                                : "No configured Host process is bound",
-                        },
-                    ],
-                },
+                result: failed("START_FAILED", error instanceof Error ? error.message : "platform-host start failed"),
                 observedEffects: [],
             };
-        },
-        doctor: () => ({ result: base, observedEffects: [] }),
-        start: async () => ({
-            result: service ? { ...base, data: await service.start() } : unbound,
-            observedEffects: service ? ["Manage the platform-host process"] : [],
-        }),
-        stop: async () => {
-            if (service)
-                await service.stop();
-            return {
-                result: service ? base : unbound,
-                observedEffects: service ? ["Manage the platform-host process"] : [],
-            };
-        },
-        restart: async () => ({
-            result: service ? { ...base, data: await service.restart() } : unbound,
-            observedEffects: service ? ["Manage the platform-host process"] : [],
-        }),
-        uninstall: async () => {
-            if (service)
-                await service.stop();
+        }
+    },
+    stop: async (context) => {
+        const service = services.get(key(context));
+        if (service) {
+            await service.stop();
+            services.delete(key(context));
             return {
-                // Uninstall is idempotent: an unbound service means there is no
-                // process to stop before package removal. Runtime readiness still
-                // fails closed in status/start/verify.
                 result: base,
-                observedEffects: service ? ["Manage the platform-host process"] : [],
+                observedEffects: ["Manage the platform-host process"],
             };
-        },
-    };
-}
-export const behaviorAdapter = createBehaviorAdapter();
-const REQUIRED_CONFIG = [
-    "stateRoot",
-    "workspaceRoot",
-    "gatewayTransportCredentialFile",
-    "executionBaseUrl",
-    "executionTransportCredentialFile",
-    "modelBaseUrl",
-    "modelTransportCredentialFile",
-];
-// Binds the real Host process only when materialized owner config and required
-// dependency composition are available. Unbound bindings still carry owner
-// config so status remains authoritative. The heavy src import is deferred
-// until a real binding is requested.
-export async function createProductionBinding(input) {
-    const config = input.config;
-    const unboundBinding = (configValid = true) => ({
-        behaviorAdapter: createBehaviorAdapter(undefined, config, configValid),
-    });
-    if (!REQUIRED_CONFIG.every((key) => config[key] !== undefined))
-        return unboundBinding();
-    // The Platform Host's public loopback endpoint is already a cross-module
-    // contract: Execution calls it through identity.endpoint. Reuse that
-    // materialized endpoint as the listener instead of binding an ephemeral port
-    // that no dependent module could discover after `start`.
-    const executionRuntime = input.configByModuleRef.get("execution-runtime");
-    const advertised = executionRuntime?.["identity.endpoint"];
-    if (!advertised)
-        return unboundBinding();
-    let listener;
-    try {
-        listener = new URL(advertised);
-    }
-    catch {
-        return unboundBinding();
-    }
-    if (listener.protocol !== "http:" || listener.pathname !== "/")
-        return unboundBinding();
-    const port = listener.port === "" ? 80 : Number(listener.port);
-    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
-        return unboundBinding();
-    const { createPlatformHost, parsePlatformHostConfig } = await import("../src/index.js");
-    let hostConfig;
-    try {
-        hostConfig = parsePlatformHostConfig({
-            stateRoot: config.stateRoot,
-            workspaceRoot: config.workspaceRoot,
-            host: listener.hostname,
-            port,
-            executionBaseUrl: config.executionBaseUrl,
-            executionTransportCredentialFile: config.executionTransportCredentialFile,
-            modelBaseUrl: config.modelBaseUrl,
-            modelTransportCredentialFile: config.modelTransportCredentialFile,
-            gatewayTransportCredentialFile: config.gatewayTransportCredentialFile,
-            roles: [],
-        });
-    }
-    catch {
-        return unboundBinding(false);
-    }
-    const host = createPlatformHost({ config: hostConfig });
-    const service = {
-        start: () => host.start(),
-        stop: () => host.stop(),
-        restart: () => host.restart(),
-        status: async () => ({ readiness: (await host.status()).readiness }),
-    };
-    return { behaviorAdapter: createBehaviorAdapter(service, input.config) };
-}
+        }
+        return {
+            result: (await running(context))
+                ? failed("STOP_FAILED", "platform-host is running without an owned lifecycle handle")
+                : base,
+            observedEffects: [],
+        };
+    },
+};

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-host";
     readonly packageName: "@tomflow/proflow-platform-host";
-    readonly moduleVersion: "0.1.5";
+    readonly moduleVersion: "0.1.7";
     readonly kind: "service";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
@@ -33,67 +33,14 @@ export declare const descriptor: {
         readonly runtime: "node";
         readonly versionRange: ">=24.19.0";
     }];
-    readonly configSlots: readonly [{
-        readonly key: "stateRoot";
-        readonly type: "path";
-        readonly required: true;
-        readonly description: "Absolute .proflow owner state root";
-    }, {
-        readonly key: "workspaceRoot";
-        readonly type: "path";
-        readonly required: true;
-        readonly description: "Absolute Task document workspace root";
-    }, {
-        readonly key: "gatewayTransportCredentialFile";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the dedicated credential accepted from agent-gateway";
-    }, {
-        readonly key: "executionBaseUrl";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Execution Runtime public transport";
-    }, {
-        readonly key: "executionTransportCredentialFile";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the credential used for Platform Host calls to Execution Runtime";
-    }, {
-        readonly key: "modelTransportCredentialFile";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the credential used for Platform Host calls to Model Runtime";
-    }, {
-        readonly key: "modelBaseUrl";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Model Runtime public transport";
-    }];
-    readonly lifecycle: {
-        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor", "start", "stop", "restart", "uninstall"];
-    };
-    readonly verification: {
-        readonly checks: readonly [{
-            readonly id: "platform-host-readiness";
-            readonly description: "Host transport and current owner dependencies are ready";
-            readonly lifecycle: "verify";
-        }];
-    };
+    readonly configSlots: readonly [];
     readonly effects: readonly [{
         readonly kind: "process";
         readonly description: "Manage the platform-host process";
         readonly retention: "remove";
     }];
-    readonly documentation: readonly [{
-        readonly id: "overview";
-        readonly path: "./README.md";
-        readonly description: "Platform Host package overview";
-    }, {
-        readonly id: "configuration";
-        readonly path: "./CONFIGURATION.md";
-        readonly description: "Module configuration fields, sources and materialization instructions";
-    }];
+    readonly documentation: {
+        readonly docs: "DOCS.md";
+        readonly setup: "SETUP.md";
+    };
 };

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-host",
     packageName: "@tomflow/proflow-platform-host",
-    moduleVersion: "0.1.5",
+    moduleVersion: "0.1.7",
     kind: "service",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",
@@ -42,75 +42,7 @@ export const descriptor = {
             versionRange: ">=24.19.0",
         },
     ],
-    configSlots: [
-        {
-            key: "stateRoot",
-            type: "path",
-            required: true,
-            description: "Absolute .proflow owner state root",
-        },
-        {
-            key: "workspaceRoot",
-            type: "path",
-            required: true,
-            description: "Absolute Task document workspace root",
-        },
-        {
-            key: "gatewayTransportCredentialFile",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the dedicated credential accepted from agent-gateway",
-        },
-        {
-            key: "executionBaseUrl",
-            type: "url",
-            required: true,
-            description: "Loopback Execution Runtime public transport",
-        },
-        {
-            key: "executionTransportCredentialFile",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the credential used for Platform Host calls to Execution Runtime",
-        },
-        {
-            key: "modelTransportCredentialFile",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the credential used for Platform Host calls to Model Runtime",
-        },
-        {
-            key: "modelBaseUrl",
-            type: "url",
-            required: true,
-            description: "Loopback Model Runtime public transport",
-        },
-    ],
-    lifecycle: {
-        supported: [
-            "describe",
-            "preflight",
-            "status",
-            "verify",
-            "doctor",
-            "start",
-            "stop",
-            "restart",
-            "uninstall",
-        ],
-    },
-    verification: {
-        checks: [
-            {
-                id: "platform-host-readiness",
-                description: "Host transport and current owner dependencies are ready",
-                lifecycle: "verify",
-            },
-        ],
-    },
+    configSlots: [],
     effects: [
         {
             kind: "process",
@@ -118,16 +50,8 @@ export const descriptor = {
             retention: "remove",
         },
     ],
-    documentation: [
-        {
-            id: "overview",
-            path: "./README.md",
-            description: "Platform Host package overview",
-        },
-        {
-            id: "configuration",
-            path: "./CONFIGURATION.md",
-            description: "Module configuration fields, sources and materialization instructions",
-        },
-    ],
+    documentation: {
+        docs: "DOCS.md",
+        setup: "SETUP.md",
+    },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-host",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -19,23 +19,24 @@
     "proflow.module.json",
     "conformance.json",
     "README.md",
-    "CONFIGURATION.md"
+    "DOCS.md",
+    "SETUP.md"
   ],
   "dependencies": {
     "zod": "4.1.12",
-    "@tomflow/proflow-agent-runtime": "^0.1.3",
-    "@tomflow/proflow-execution-browser-extension": "^0.1.4",
-    "@tomflow/proflow-execution-contracts": "^0.1.3",
-    "@tomflow/proflow-task-store-sqlite": "^0.1.3",
-    "@tomflow/proflow-module-contract": "^0.1.3",
-    "@tomflow/proflow-task-orchestration": "^0.1.2",
-    "@tomflow/proflow-task-migration-runner": "^0.1.3"
+    "@tomflow/proflow-agent-runtime": "^0.1.5",
+    "@tomflow/proflow-module-contract": "^0.1.5",
+    "@tomflow/proflow-execution-browser-extension": "^0.1.6",
+    "@tomflow/proflow-task-migration-runner": "^0.1.5",
+    "@tomflow/proflow-task-store-sqlite": "^0.1.5",
+    "@tomflow/proflow-task-orchestration": "^0.1.4",
+    "@tomflow/proflow-execution-contracts": "^0.1.5"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.3",
-    "@tomflow/proflow-model-runtime": "^0.1.6",
-    "@tomflow/proflow-agent-gateway": "^0.1.5",
-    "@tomflow/proflow-execution-runtime": "^0.1.6"
+    "@tomflow/proflow-execution-runtime": "^0.1.8",
+    "@tomflow/proflow-deployment-conformance": "^0.1.5",
+    "@tomflow/proflow-agent-gateway": "^0.1.7",
+    "@tomflow/proflow-model-runtime": "^0.1.8"
   },
   "description": "Provides the ProFlow local application composition root that binds Task, Agent, Execution and Model owner transports.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-host",
 	"packageName": "@tomflow/proflow-platform-host",
-	"moduleVersion": "0.1.5",
+	"moduleVersion": "0.1.7",
 	"kind": "service",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
@@ -42,75 +42,7 @@
 			"versionRange": ">=24.19.0"
 		}
 	],
-	"configSlots": [
-		{
-			"key": "stateRoot",
-			"type": "path",
-			"required": true,
-			"description": "Absolute .proflow owner state root"
-		},
-		{
-			"key": "workspaceRoot",
-			"type": "path",
-			"required": true,
-			"description": "Absolute Task document workspace root"
-		},
-		{
-			"key": "gatewayTransportCredentialFile",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the dedicated credential accepted from agent-gateway"
-		},
-		{
-			"key": "executionBaseUrl",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Execution Runtime public transport"
-		},
-		{
-			"key": "executionTransportCredentialFile",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the credential used for Platform Host calls to Execution Runtime"
-		},
-		{
-			"key": "modelTransportCredentialFile",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the credential used for Platform Host calls to Model Runtime"
-		},
-		{
-			"key": "modelBaseUrl",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Model Runtime public transport"
-		}
-	],
-	"lifecycle": {
-		"supported": [
-			"describe",
-			"preflight",
-			"status",
-			"verify",
-			"doctor",
-			"start",
-			"stop",
-			"restart",
-			"uninstall"
-		]
-	},
-	"verification": {
-		"checks": [
-			{
-				"id": "platform-host-readiness",
-				"description": "Host transport and current owner dependencies are ready",
-				"lifecycle": "verify"
-			}
-		]
-	},
+	"configSlots": [],
 	"effects": [
 		{
 			"kind": "process",
@@ -118,16 +50,8 @@
 			"retention": "remove"
 		}
 	],
-	"documentation": [
-		{
-			"id": "overview",
-			"path": "./README.md",
-			"description": "Platform Host package overview"
-		},
-		{
-			"id": "configuration",
-			"path": "./CONFIGURATION.md",
-			"description": "Module configuration fields, sources and materialization instructions"
-		}
-	]
+	"documentation": {
+		"docs": "DOCS.md",
+		"setup": "SETUP.md"
+	}
 }

package/CONFIGURATION.md

@@ -1,29 +0,0 @@
-# platform-host configuration
-
-Canonical public config: `.proflow/config/platform-host.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 |
-|---|---|---:|---:|---|---|
-| `stateRoot` | `path` | yes | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | Absolute .proflow owner state root |
-| `workspaceRoot` | `path` | yes | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | Absolute Task document workspace root |
-| `gatewayTransportCredentialFile` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the dedicated credential accepted from agent-gateway |
-| `executionBaseUrl` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Execution Runtime public transport |
-| `executionTransportCredentialFile` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the credential used for Platform Host calls to Execution Runtime |
-| `modelTransportCredentialFile` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the credential used for Platform Host calls to Model Runtime |
-| `modelBaseUrl` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Model Runtime public transport |
-
-## Materialize
-
-Create or update the canonical JSON object at:
-
-`.proflow/config/platform-host.json`
-
-Use only declared keys and string values. Do not create a second Platform configuration database.
-
-## 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.