@tomflow/proflow-agent-gateway 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @tomflow/proflow-agent-gateway
+
+The sole Custom GPT Actions HTTP ingress and OpenAI transport anti-corruption layer.
+
+It authenticates role-scoped credentials, validates typed body/path/query identity, routes business-purpose Actions to owner contracts, and normalizes File Bridge transport. It is stateless with respect to Worker Turns and owns no Task/Execution/Artifact/File business store. Product GPT-facing New Task `createTask/listRegisteredRoles/getRegisteredRole` is not part of the v1 main Action surface; New Task is Extension-first.

package/conformance.json

@@ -0,0 +1 @@
+{ "contract": "proflow.conformance.v1", "levels": ["C1", "C2", "C3"] }

package/dist/deployment/adapter.d.ts

@@ -0,0 +1,452 @@
+type GatewayProcess = {
+    start(): Promise<{
+        host: string;
+        port: number;
+    }>;
+    stop(): Promise<void>;
+    restart(): Promise<{
+        host: string;
+        port: number;
+    }>;
+    readiness(): Promise<{
+        status: "READY" | "NOT_READY";
+    }>;
+    status(): unknown;
+};
+export declare function createBehaviorAdapter(service?: GatewayProcess): {
+    describe: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    status: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        } | {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: unknown;
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data: unknown;
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    }>;
+    verify: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    }>;
+    doctor: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    start: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: {
+                host: string;
+                port: number;
+            };
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            status: "ACTION_REQUIRED";
+            ok: boolean;
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+    stop: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        } | {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    uninstall: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        } | {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    restart: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: {
+                host: string;
+                port: number;
+            };
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            status: "ACTION_REQUIRED";
+            ok: boolean;
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+};
+export declare const behaviorAdapter: {
+    describe: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    status: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        } | {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: unknown;
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data: unknown;
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    }>;
+    verify: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            checks: {
+                id: string;
+                status: "FAIL" | "PASS";
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    }>;
+    doctor: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    start: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: {
+                host: string;
+                port: number;
+            };
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            status: "ACTION_REQUIRED";
+            ok: boolean;
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+    stop: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        } | {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    uninstall: () => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+        } | {
+            readonly contract: "deployment.result.v1";
+            readonly moduleRef: "agent-gateway";
+            readonly moduleVersion: "0.1.0";
+            readonly ok: false;
+            readonly status: "ACTION_REQUIRED";
+            readonly actionRequired: {
+                readonly action: "compose-gateway";
+                readonly description: "Provide owner ports and process configuration";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    restart: () => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            data: {
+                host: string;
+                port: number;
+            };
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "agent-gateway";
+            moduleVersion: "0.1.0";
+            status: "ACTION_REQUIRED";
+            ok: boolean;
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+};
+export declare function createServiceProcessBinding(input: {
+    moduleRef: string;
+    config: Record<string, string>;
+    workspaceRoot: string;
+    configByModuleRef: ReadonlyMap<string, Record<string, string>>;
+}): Promise<{
+    serviceProcess: {
+        contract: "deployment.service-process.v1";
+        bin: "proflow-agent-gateway";
+        startCommand: "start";
+        config: Record<string, unknown>;
+    };
+    behaviorAdapter: Record<string, unknown>;
+} | undefined>;
+export declare function createProductionBinding(input: {
+    moduleRef: string;
+    config: Record<string, string>;
+    workspaceRoot: string;
+    configByModuleRef: ReadonlyMap<string, Record<string, string>>;
+}): Promise<{
+    behaviorAdapter: Record<string, unknown>;
+} | undefined>;
+export {};

package/dist/deployment/adapter.js

@@ -0,0 +1,240 @@
+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-gateway",
+        description: "Provide owner ports and process configuration",
+    },
+};
+export function createBehaviorAdapter(service) {
+    return {
+        describe: () => ({ result: base, observedEffects: [] }),
+        preflight: () => ({ result: base, observedEffects: [] }),
+        status: async () => {
+            const processStatus = service?.status();
+            const readiness = service ? await service.readiness() : undefined;
+            const ready = readiness?.status === "READY";
+            return {
+                result: service
+                    ? {
+                        ...(ready
+                            ? base
+                            : {
+                                ...base,
+                                ok: false,
+                                status: "ACTION_REQUIRED",
+                                actionRequired: {
+                                    action: "repair-gateway",
+                                    description: "Gateway is not READY",
+                                },
+                            }),
+                        data: processStatus,
+                        checks: [
+                            {
+                                id: "gateway-readiness",
+                                status: ready ? "PASS" : "FAIL",
+                                message: `Gateway readiness is ${readiness?.status ?? "NOT_READY"}`,
+                            },
+                        ],
+                    }
+                    : unbound,
+                observedEffects: [],
+            };
+        },
+        verify: async () => {
+            const readiness = service ? await service.readiness() : undefined;
+            const ready = readiness?.status === "READY";
+            return {
+                result: {
+                    ...(service && ready
+                        ? base
+                        : service
+                            ? {
+                                ...base,
+                                ok: false,
+                                status: "ACTION_REQUIRED",
+                                actionRequired: {
+                                    action: "repair-gateway",
+                                    description: "Gateway is not READY",
+                                },
+                            }
+                            : unbound),
+                    checks: [
+                        {
+                            id: "gateway-readiness",
+                            status: ready ? "PASS" : "FAIL",
+                            message: service
+                                ? `Gateway readiness is ${readiness?.status ?? "NOT_READY"}`
+                                : "No configured Gateway process is bound",
+                        },
+                    ],
+                },
+                observedEffects: [],
+            };
+        },
+        doctor: () => ({ result: base, observedEffects: [] }),
+        start: async () => ({
+            result: {
+                ...base,
+                ...(service
+                    ? { data: await service.start() }
+                    : {
+                        status: "ACTION_REQUIRED",
+                        ok: false,
+                        actionRequired: {
+                            action: "compose-gateway",
+                            description: "Provide owner ports before starting Gateway",
+                        },
+                    }),
+            },
+            observedEffects: service ? ["Manage the declared service process"] : [],
+        }),
+        stop: async () => {
+            if (service)
+                await service.stop();
+            return {
+                result: service ? base : unbound,
+                observedEffects: service ? ["Manage the declared service process"] : [],
+            };
+        },
+        uninstall: async () => {
+            if (service)
+                await service.stop();
+            return {
+                result: service ? base : unbound,
+                observedEffects: service ? ["Manage the declared service process"] : [],
+            };
+        },
+        restart: async () => ({
+            result: {
+                ...base,
+                ...(service
+                    ? { data: await service.restart() }
+                    : {
+                        status: "ACTION_REQUIRED",
+                        ok: false,
+                        actionRequired: {
+                            action: "compose-gateway",
+                            description: "Provide owner ports before restarting Gateway",
+                        },
+                    }),
+            },
+            observedEffects: service ? ["Manage the declared service process"] : [],
+        }),
+    };
+}
+export const behaviorAdapter = createBehaviorAdapter();
+export async function createServiceProcessBinding(input) {
+    const localBaseUrl = input.config.localBaseUrl;
+    const publicBaseUrl = input.config.publicBaseUrl;
+    const downstreamCredentialFile = input.config.downstreamCredentialFile;
+    const platformHost = input.configByModuleRef.get("platform-host");
+    const executionRuntime = input.configByModuleRef.get("execution-runtime");
+    const stateRoot = platformHost?.stateRoot;
+    const downstreamBaseUrl = executionRuntime?.["identity.endpoint"];
+    if (!localBaseUrl ||
+        !publicBaseUrl ||
+        !downstreamCredentialFile ||
+        !stateRoot ||
+        !downstreamBaseUrl) {
+        return undefined;
+    }
+    const listener = new URL(localBaseUrl);
+    if (listener.protocol !== "http:" ||
+        !new Set(["127.0.0.1", "localhost", "::1", "[::1]"]).has(listener.hostname) ||
+        listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const [{ join }, { parseAgentGatewayProcessConfig }] = await Promise.all([
+        import("node:path"),
+        import("../src/process.js"),
+    ]);
+    const processConfig = parseAgentGatewayProcessConfig({
+        host: listener.hostname,
+        port,
+        publicBaseUrl,
+        downstreamBaseUrl,
+        credentialFile: join(stateRoot, "agent", "secrets", "role-credentials.json"),
+        downstreamCredentialFile,
+    });
+    const probeService = {
+        async start() {
+            throw new Error("managed by Platform CLI service supervisor");
+        },
+        async stop() { },
+        async restart() {
+            throw new Error("managed by Platform CLI service supervisor");
+        },
+        async readiness() {
+            try {
+                const response = await fetch(new URL("/ready", listener));
+                return {
+                    status: response.ok ? "READY" : "NOT_READY",
+                };
+            }
+            catch {
+                return { status: "NOT_READY" };
+            }
+        },
+        status: () => ({
+            endpoint: listener.href.replace(/\/$/, ""),
+            managed: true,
+        }),
+    };
+    return {
+        serviceProcess: {
+            contract: "deployment.service-process.v1",
+            bin: "proflow-agent-gateway",
+            startCommand: "start",
+            config: processConfig,
+        },
+        behaviorAdapter: createBehaviorAdapter(probeService),
+    };
+}
+export async function createProductionBinding(input) {
+    const localBaseUrl = input.config.localBaseUrl;
+    const publicBaseUrl = input.config.publicBaseUrl;
+    const downstreamCredentialFile = input.config.downstreamCredentialFile;
+    const platformHost = input.configByModuleRef.get("platform-host");
+    const executionRuntime = input.configByModuleRef.get("execution-runtime");
+    const stateRoot = platformHost?.stateRoot;
+    const downstreamBaseUrl = executionRuntime?.["identity.endpoint"];
+    if (!localBaseUrl ||
+        !publicBaseUrl ||
+        !downstreamCredentialFile ||
+        !stateRoot ||
+        !downstreamBaseUrl) {
+        return undefined;
+    }
+    const listener = new URL(localBaseUrl);
+    if (listener.protocol !== "http:" ||
+        !new Set(["127.0.0.1", "localhost", "::1", "[::1]"]).has(listener.hostname) ||
+        listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const [{ join }, { createAgentGatewayProcess, parseAgentGatewayProcessConfig },] = await Promise.all([import("node:path"), import("../src/process.js")]);
+    const service = await createAgentGatewayProcess({
+        config: parseAgentGatewayProcessConfig({
+            host: listener.hostname,
+            port,
+            publicBaseUrl,
+            downstreamBaseUrl,
+            credentialFile: join(stateRoot, "agent", "secrets", "role-credentials.json"),
+            downstreamCredentialFile,
+        }),
+    });
+    return { behaviorAdapter: createBehaviorAdapter(service) };
+}