@tomflow/proflow-agent-gateway 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-agent-gateway
 
+## 0.1.12
+
+### Patch Changes
+
+- Distinguish dependency blocking from verified failure, expose Module-owned status diagnostics, remove automatic docs paging, consolidate start checks, add contextual help, and clarify uninstall output.
+
+## 0.1.11
+
+### Patch Changes
+
+- Upgrade the ProFlow terminal experience, stream Registry and package-manager progress, publish structured Chinese Module documentation, and provide numbered package-owned Setup assistants.
+
 ## 0.1.10
 
 ### Patch Changes

package/DOCS.md

@@ -1,14 +1,38 @@
-# agent-gateway
+# agent-gateway — 智能体动作网关
 
-Agent Gateway（智能体网关）是 Custom GPT Actions 的公网入口。它校验角色身份、请求格式和权限，再把请求转发给 ProFlow 内部服务。
+## 模块定位与作用
 
-## 什么时候需要
+Agent Gateway（智能体网关）是 Custom GPT Actions 的唯一公网入口。它负责认证角色身份、校验请求、路由到领域 Public API，并把结果规范化返回 ChatGPT。
 
-当 Custom GPT 需要调用 ProFlow 的任务、协作或执行能力时，必须启动该服务。
+## 主要能力
 
-## 使用前提
+- 校验 Role Bearer Key、请求 Schema、权限和版本。
+- 路由 Task、Agent Runtime 与 Execution 的公开能力。
+- 暴露静态 OpenAPI 所需的 HTTPS Action 接口，不保存业务数据。
 
-- Platform Host（平台主服务）已经就绪。
-- Dev Tunnel（开发隧道）已经提供可公开访问的 HTTPS 地址。
+## 提供的 API 与 Public Contract
 
-网关不保存业务数据；配置完成后使用 `platform start` 统一启动。
+- 提供 `custom-gpt-actions-gateway` Contract，版本 `1.0.0`。
+- 对外提供 Custom GPT Actions HTTP API；内部只调用已声明的领域 Contract。
+
+## 依赖的 Module、Contract 和外部资源
+
+- 依赖 `agent-runtime`、`task-orchestration`、`execution`、`platform-host` 和 `public-ingress`，兼容版本均为 `>=1.0.0 <2.0.0`。
+
+## 运行形态与生命周期
+
+类型为 Service（服务），由独立进程监听本地端口，经 Dev Tunnel 暴露公开 HTTPS 地址。
+
+## 使用方式
+
+完成 Platform Host 与 Dev Tunnel 配置后运行 `platform start`。Custom GPT 使用各自 Role Key 调用该网关。
+
+## 职责边界与限制
+
+不直接读取数据库、不执行 Shell/Git、不推进 Task，也不拥有 Tunnel 登录和域名生命周期。
+
+## 术语
+
+- Gateway（网关）：外部协议与内部领域接口之间的受控适配层。
+- Public Ingress（公网入口）：由 Dev Tunnel 提供的 HTTPS 访问能力。
+- Bearer Key（持有者凭据）：用于识别固定 Role 的认证信息。

package/SETUP.md

@@ -1,10 +1,19 @@
 # @tomflow/proflow-agent-gateway — Module Setup
 
-## STEP-AGENT-GATEWAY-01 — 完成模块自动配置
+## STEP-AGENT-GATEWAY-01 — 准备公开入口
+
+Responsible: EXTERNAL
+Interactive executable: `platform setup --module dev-tunnel`
+Non-interactive executable: `platform setup --module dev-tunnel`
+Required inputs: persistent Tunnel and public HTTPS URL
+Verify: `platform status`
+Success condition: `dev-tunnel.setupStatus=READY`.
+
+## STEP-AGENT-GATEWAY-02 — 启动平台主服务
 
 Responsible: AI
-Interactive executable: `platform setup --module agent-gateway`
-Non-interactive executable: `platform setup --module agent-gateway`
+Interactive executable: `platform setup --module platform-host`
+Non-interactive executable: `platform setup --module platform-host`
 Required inputs: none
 Verify: `platform status`
-Success condition: `agent-gateway.setupStatus=READY`.
+Success condition: `platform-host.setupStatus=READY`.

package/dist/deployment/adapter.d.ts

@@ -6,7 +6,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             data: {
                 localBaseUrl: string;
                 publicBaseUrl?: string;
@@ -20,7 +20,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "agent-gateway";
-            readonly moduleVersion: "0.1.10";
+            readonly moduleVersion: "0.1.12";
         };
         observedEffects: string[];
     }>;
@@ -30,10 +30,17 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             data: {
-                setupStatus: "FAILED" | "READY";
+                setupStatus: "BLOCKED" | "READY";
                 runtimeStatus: "RUNNING" | "STOPPED";
+                issues?: {
+                    scope: "SETUP";
+                    code: string;
+                    message: string;
+                    relatedModuleRefs: string[];
+                    nextCommand: string;
+                }[];
             };
         };
         observedEffects: never[];
@@ -44,11 +51,11 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "agent-gateway";
-            readonly moduleVersion: "0.1.10";
+            readonly moduleVersion: "0.1.12";
         } | {
             contract: "deployment.result.v1";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             ok: false;
             status: "FAILED";
             error: {
@@ -59,17 +66,32 @@ export declare const behaviorAdapter: {
             data: {
                 readonly steps: readonly [{
                     readonly id: "STEP-AGENT-GATEWAY-01";
-                    readonly title: "等待公开入口与 Platform Host";
+                    readonly title: "等待 Public Ingress";
+                    readonly description: "Gateway 需要稳定的公开 HTTPS 地址。";
                     readonly state: "BLOCKED";
                     readonly responsible: "EXTERNAL";
                     readonly execution: {
-                        readonly interactive: "platform setup --module agent-gateway";
-                        readonly nonInteractive: "platform setup --module agent-gateway";
+                        readonly interactive: "platform setup --module dev-tunnel";
+                        readonly nonInteractive: "platform setup --module dev-tunnel";
                     };
                     readonly requiredInputs: readonly [];
                     readonly verify: "platform status";
                     readonly successCondition: "配置状态变为“已就绪”";
-                    readonly blockedReason: "public-ingress 或 platform-host 的共享事实尚不可用";
+                    readonly blockedReason: "dev-tunnel 尚未发布 publicBaseUrl";
+                }, {
+                    readonly id: "STEP-AGENT-GATEWAY-02";
+                    readonly title: "等待 Platform Host";
+                    readonly description: "Gateway 下游应用端点和凭据尚不可用。";
+                    readonly state: "BLOCKED";
+                    readonly responsible: "EXTERNAL";
+                    readonly execution: {
+                        readonly interactive: "platform setup --module platform-host";
+                        readonly nonInteractive: "platform setup --module platform-host";
+                    };
+                    readonly requiredInputs: readonly [];
+                    readonly verify: "platform status";
+                    readonly successCondition: "platform-host 已发布 endpoint、stateRoot 和 transport credential";
+                    readonly blockedReason: "platform-host 尚未就绪";
                 }];
             };
         };
@@ -81,7 +103,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             data: {
                 docs: string;
             };
@@ -94,7 +116,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             data: {
                 host: string;
                 port: number;
@@ -105,7 +127,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             ok: false;
             status: "FAILED";
             error: {
@@ -122,7 +144,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "agent-gateway";
-            readonly moduleVersion: "0.1.10";
+            readonly moduleVersion: "0.1.12";
         };
         observedEffects: string[];
     } | {
@@ -131,11 +153,11 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "agent-gateway";
-            readonly moduleVersion: "0.1.10";
+            readonly moduleVersion: "0.1.12";
         } | {
             contract: "deployment.result.v1";
             moduleRef: "agent-gateway";
-            moduleVersion: "0.1.10";
+            moduleVersion: "0.1.12";
             ok: false;
             status: "FAILED";
             error: {

package/dist/deployment/adapter.js

@@ -14,17 +14,33 @@ const blockedSetupPlan = {
     steps: [
         {
             id: "STEP-AGENT-GATEWAY-01",
-            title: "等待公开入口与 Platform Host",
+            title: "等待 Public Ingress",
+            description: "Gateway 需要稳定的公开 HTTPS 地址。",
             state: "BLOCKED",
             responsible: "EXTERNAL",
             execution: {
-                interactive: "platform setup --module agent-gateway",
-                nonInteractive: "platform setup --module agent-gateway",
+                interactive: "platform setup --module dev-tunnel",
+                nonInteractive: "platform setup --module dev-tunnel",
             },
             requiredInputs: [],
             verify: "platform status",
             successCondition: "配置状态变为“已就绪”",
-            blockedReason: "public-ingress 或 platform-host 的共享事实尚不可用",
+            blockedReason: "dev-tunnel 尚未发布 publicBaseUrl",
+        },
+        {
+            id: "STEP-AGENT-GATEWAY-02",
+            title: "等待 Platform Host",
+            description: "Gateway 下游应用端点和凭据尚不可用。",
+            state: "BLOCKED",
+            responsible: "EXTERNAL",
+            execution: {
+                interactive: "platform setup --module platform-host",
+                nonInteractive: "platform setup --module platform-host",
+            },
+            requiredInputs: [],
+            verify: "platform status",
+            successCondition: "platform-host 已发布 endpoint、stateRoot 和 transport credential",
+            blockedReason: "platform-host 尚未就绪",
         },
     ],
 };
@@ -106,20 +122,34 @@ export const behaviorAdapter = {
             observedEffects: service ? ["Manage the declared service process"] : [],
         };
     },
-    status: async (context) => ({
-        result: {
-            ...base,
-            data: {
-                setupStatus: (await dependencies(context))
-                    ? "READY"
-                    : "FAILED",
-                runtimeStatus: (await running(context))
-                    ? "RUNNING"
-                    : "STOPPED",
+    status: async (context) => {
+        const ready = await dependencies(context);
+        return {
+            result: {
+                ...base,
+                data: {
+                    setupStatus: ready ? "READY" : "BLOCKED",
+                    runtimeStatus: (await running(context))
+                        ? "RUNNING"
+                        : "STOPPED",
+                    ...(ready
+                        ? {}
+                        : {
+                            issues: [
+                                {
+                                    scope: "SETUP",
+                                    code: "UPSTREAM_NOT_READY",
+                                    message: "等待 dev-tunnel 发布公开 HTTPS 地址，并等待 platform-host 发布下游端点与传输凭据",
+                                    relatedModuleRefs: ["dev-tunnel", "platform-host"],
+                                    nextCommand: "platform setup --module dev-tunnel",
+                                },
+                            ],
+                        }),
+                },
             },
-        },
-        observedEffects: [],
-    }),
+            observedEffects: [],
+        };
+    },
     setup: async (context) => ({
         result: (await dependencies(context))
             ? base

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "agent-gateway";
     readonly packageName: "@tomflow/proflow-agent-gateway";
-    readonly moduleVersion: "0.1.10";
+    readonly moduleVersion: "0.1.12";
     readonly kind: "service";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "agent-gateway",
     packageName: "@tomflow/proflow-agent-gateway",
-    moduleVersion: "0.1.10",
+    moduleVersion: "0.1.12",
     kind: "service",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-agent-gateway",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -25,18 +25,18 @@
   ],
   "dependencies": {
     "zod": "4.1.12",
-    "@tomflow/proflow-module-contract": "^0.1.10"
+    "@tomflow/proflow-module-contract": "^0.1.12"
   },
   "devDependencies": {
-    "@tomflow/proflow-agent-runtime": "^0.1.8",
-    "@tomflow/proflow-deployment-conformance": "^0.1.8",
-    "@tomflow/proflow-execution-browser-extension": "^0.1.9",
-    "@tomflow/proflow-execution-runtime": "^0.1.11",
-    "@tomflow/proflow-platform-host": "^0.1.10",
-    "@tomflow/proflow-task-orchestration": "^0.1.7",
-    "@tomflow/proflow-task-migration-runner": "^0.1.8",
-    "@tomflow/proflow-execution-local": "^0.1.9",
-    "@tomflow/proflow-task-store-sqlite": "^0.1.8"
+    "@tomflow/proflow-agent-runtime": "^0.1.9",
+    "@tomflow/proflow-execution-browser-extension": "^0.1.12",
+    "@tomflow/proflow-execution-local": "^0.1.11",
+    "@tomflow/proflow-execution-runtime": "^0.1.13",
+    "@tomflow/proflow-platform-host": "^0.1.12",
+    "@tomflow/proflow-task-migration-runner": "^0.1.10",
+    "@tomflow/proflow-task-orchestration": "^0.1.8",
+    "@tomflow/proflow-task-store-sqlite": "^0.1.10",
+    "@tomflow/proflow-deployment-conformance": "^0.1.10"
   },
   "description": "The sole Custom GPT Actions HTTP ingress and OpenAI transport anti-corruption layer.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "agent-gateway",
 	"packageName": "@tomflow/proflow-agent-gateway",
-	"moduleVersion": "0.1.10",
+	"moduleVersion": "0.1.12",
 	"kind": "service",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",