@tomflow/proflow-platform-host 0.1.0

package/dist/deployment/adapter.js

@@ -0,0 +1,243 @@
+import { descriptor } from "./descriptor.js";
+const base = {
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+};
+const unbound = {
+    ...base,
+    ok: false,
+    status: "ACTION_REQUIRED",
+    actionRequired: {
+        action: "compose-platform-host",
+        description: "Provide validated Host configuration and owner transports",
+    },
+};
+export function createBehaviorAdapter(service) {
+    return {
+        describe: () => ({ result: base, observedEffects: [] }),
+        preflight: () => ({ result: base, observedEffects: [] }),
+        status: async () => {
+            const status = service ? await service.status() : undefined;
+            const ready = status?.readiness === "READY";
+            return {
+                result: service
+                    ? {
+                        ...(ready
+                            ? base
+                            : {
+                                ...base,
+                                ok: false,
+                                status: "ACTION_REQUIRED",
+                                actionRequired: {
+                                    action: "repair-platform-host",
+                                    description: "Platform Host is not READY",
+                                },
+                            }),
+                        data: status,
+                        checks: [
+                            {
+                                id: "platform-host-readiness",
+                                status: ready ? "PASS" : "FAIL",
+                                message: `Platform Host readiness is ${status?.readiness ?? "NOT_READY"}`,
+                            },
+                        ],
+                    }
+                    : unbound,
+                observedEffects: [],
+            };
+        },
+        verify: async () => {
+            const status = service ? await service.status() : undefined;
+            const ready = status?.readiness === "READY";
+            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",
+                        },
+                    ],
+                },
+                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();
+            return {
+                result: service ? base : unbound,
+                observedEffects: service ? ["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 the materialized config is complete;
+// otherwise stays unbound so the CLI's catalog falls back to the fail-closed
+// default. The heavy src import is deferred until a real binding is requested.
+export async function createServiceProcessBinding(input) {
+    const config = input.config;
+    if (!REQUIRED_CONFIG.every((key) => config[key] !== undefined))
+        return undefined;
+    const executionRuntime = input.configByModuleRef.get("execution-runtime");
+    const advertised = executionRuntime?.["identity.endpoint"];
+    if (!advertised)
+        return undefined;
+    const listener = new URL(advertised);
+    if (listener.protocol !== "http:" || listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const { parsePlatformHostConfig } = await import("../src/index.js");
+    const processConfig = 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: [],
+    });
+    const probeAdapter = {
+        describe: behaviorAdapter.describe,
+        preflight: behaviorAdapter.preflight,
+        verify: async () => {
+            let ready = false;
+            try {
+                ready = (await fetch(new URL("/ready", listener))).ok;
+            }
+            catch {
+                ready = false;
+            }
+            return {
+                result: ready
+                    ? {
+                        ...base,
+                        checks: [
+                            {
+                                id: "platform-host-readiness",
+                                status: "PASS",
+                                message: "Managed Platform Host /ready probe passed",
+                            },
+                        ],
+                    }
+                    : {
+                        ...base,
+                        ok: false,
+                        status: "ACTION_REQUIRED",
+                        actionRequired: {
+                            action: "repair-platform-host",
+                            description: "Managed Platform Host /ready probe failed",
+                        },
+                        checks: [
+                            {
+                                id: "platform-host-readiness",
+                                status: "FAIL",
+                                message: "Managed Platform Host /ready probe failed",
+                            },
+                        ],
+                    },
+                observedEffects: [],
+            };
+        },
+        doctor: behaviorAdapter.doctor,
+    };
+    return {
+        serviceProcess: {
+            contract: "deployment.service-process.v1",
+            bin: "proflow-platform-host",
+            startCommand: "start",
+            config: processConfig,
+        },
+        behaviorAdapter: probeAdapter,
+    };
+}
+export async function createProductionBinding(input) {
+    const config = input.config;
+    if (!REQUIRED_CONFIG.every((key) => config[key] !== undefined))
+        return undefined;
+    // 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 undefined;
+    const listener = new URL(advertised);
+    if (listener.protocol !== "http:" || listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const { createPlatformHost, parsePlatformHostConfig } = await import("../src/index.js");
+    const 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: [],
+    });
+    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) };
+}

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,96 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "platform-host";
+    readonly packageName: "@tomflow/proflow-platform-host";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "service";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "platform-architecture";
+        readonly summary: "Provides the ProFlow local application composition root that binds Task, Agent, Execution and Model owner transports.";
+    };
+    readonly provides: readonly [{
+        readonly contractRef: "platform-host";
+        readonly version: "1.0.0";
+    }];
+    readonly requires: readonly [{
+        readonly contractRef: "task-orchestration";
+        readonly versionRange: ">=1.0.0 <2.0.0";
+    }, {
+        readonly contractRef: "agent-runtime";
+        readonly versionRange: ">=1.0.0 <2.0.0";
+    }, {
+        readonly contractRef: "execution";
+        readonly versionRange: ">=1.0.0 <2.0.0";
+    }, {
+        readonly contractRef: "model-inference";
+        readonly versionRange: ">=1.0.0 <2.0.0";
+    }];
+    readonly requirements: readonly [{
+        readonly kind: "runtime";
+        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 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";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,108 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "platform-host",
+    packageName: "@tomflow/proflow-platform-host",
+    moduleVersion: "0.1.0",
+    kind: "service",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "platform-architecture",
+        summary: "Provides the ProFlow local application composition root that binds Task, Agent, Execution and Model owner transports.",
+    },
+    provides: [{ contractRef: "platform-host", version: "1.0.0" }],
+    requires: [
+        { 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: "model-inference", versionRange: ">=1.0.0 <2.0.0" },
+    ],
+    requirements: [
+        { kind: "runtime", runtime: "node", 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",
+            },
+        ],
+    },
+    effects: [
+        {
+            kind: "process",
+            description: "Manage the platform-host process",
+            retention: "remove",
+        },
+    ],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Platform Host package overview",
+        },
+    ],
+};

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createPlatformHost, loadPlatformHostConfig } from "./index.js";
+function installSelf() {
+    const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+    const result = spawnSync(executable, [
+        "--yes",
+        "@tomflow/proflow-platform-cli",
+        "install",
+        "@tomflow/proflow-platform-host",
+    ], { cwd: process.cwd(), env: process.env, stdio: "inherit" });
+    if (result.error)
+        throw result.error;
+    process.exit(result.status ?? 1);
+}
+async function main() {
+    const [command, configPath] = process.argv.slice(2);
+    if (command === "--help" || command === "-h") {
+        process.stdout.write("Usage: proflow-platform-host install | start /absolute/config.json\\n");
+        process.exit(0);
+    }
+    if (command === "install") {
+        if (configPath)
+            throw new Error("Usage: proflow-platform-host install");
+        installSelf();
+    }
+    if (command !== "start" || !configPath)
+        throw new Error("Usage: proflow-platform-host start /absolute/config.json");
+    const config = await loadPlatformHostConfig(configPath);
+    if (!config.gatewayTransportCredentialFile)
+        throw new Error("platform-host requires gatewayTransportCredentialFile for authenticated Gateway transport");
+    if (!config.modelTransportCredentialFile)
+        throw new Error("platform-host requires modelTransportCredentialFile for authenticated Model Runtime transport");
+    if (!config.executionTransportCredentialFile)
+        throw new Error("platform-host requires executionTransportCredentialFile for authenticated Execution Runtime transport");
+    const host = createPlatformHost({
+        config,
+        log: (entry) => process.stderr.write(`${JSON.stringify(entry)}\n`),
+    });
+    const address = await host.start();
+    process.stdout.write(`${JSON.stringify({ status: "RUNNING", ...address })}\n`);
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void host.stop().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await new Promise(() => { });
+}
+if (import.meta.main) {
+    await main();
+}