@1agents/dreammate-network 0.2.0 → 0.3.0

package/dist/typescript/types.d.ts

@@ -8,7 +8,11 @@
  *
  * @packageDocumentation
  */
-export declare const PROTOCOL_VERSION = "0.1.0";
+/**
+ * 协议版本，与本包的 package.json 版本保持一致——两个版本号会让人永远猜不准
+ * 该看哪个。服务在 `manifest.metadata.protocol_version` 里报告它遵循的版本。
+ */
+export declare const PROTOCOL_VERSION = "0.3.0";
 /** `session://<node>/<runtime>/<session_id>` */
 export type SessionURI = `session://${string}/${string}/${string}`;
 /** 资源寻址，如 `recording://tingqi-01/abc`、`speaker://tingqi-001/speaker-23` */
@@ -57,6 +61,11 @@ export interface AccessDescriptor {
  * 与 docs/protocol.md §6 的表格一一对应，改动必须同步两边。
  */
 export declare const DEFAULT_PORTS: {
+    /**
+     * 本机 node agent（`@1agents/dreammate-node`）。**固定端口**，不可改：
+     * 它是整台机器对网络的唯一入口，外部节点靠"探 36908"找到这台机器上的一切。
+     */
+    readonly "node-agent": 36908;
     readonly "session-registry": 7777;
     readonly "data-service": 7778;
     readonly "control-plane": 7779;
@@ -82,6 +91,8 @@ export type ServiceKind = "generic" | "agent_runtime" | "session_registry" | "re
  * 三层结构是 Node → Service → Capability / Resource，
  * 不要把 Capability 扁平铺到 Node 上。
  */
+/** 这个 Service 能被谁连上。省略时按 `network` 理解。 */
+export type Reachability = "localhost" | "network";
 export interface Service {
     id: string;
     name?: string | null;
@@ -91,6 +102,15 @@ export interface Service {
     capabilities: Capability[];
     resources?: ResourceDescriptor[];
     access?: AccessDescriptor[];
+    /**
+     * 只监听回环的服务，外部节点发现得了但连不上。node agent 如实转述这个
+     * 声明而**不做代理**——调用方看到 `localhost` 就知道不用白跑一趟。
+     */
+    reachability?: Reachability;
+    /** 实际监听端口。不必等于 {@link DEFAULT_PORTS} 里的默认值。 */
+    port?: number | null;
+    /** 存活探测路径，默认 `/health`。 */
+    health?: string | null;
     metadata?: Record<string, unknown>;
 }
 /**

package/dist/typescript/types.js

@@ -8,7 +8,11 @@
  *
  * @packageDocumentation
  */
-export const PROTOCOL_VERSION = "0.1.0";
+/**
+ * 协议版本，与本包的 package.json 版本保持一致——两个版本号会让人永远猜不准
+ * 该看哪个。服务在 `manifest.metadata.protocol_version` 里报告它遵循的版本。
+ */
+export const PROTOCOL_VERSION = "0.3.0";
 /* ------------------------------------------------------------------ *
  * 发现
  * ------------------------------------------------------------------ */
@@ -22,6 +26,11 @@ export const PROTOCOL_VERSION = "0.1.0";
  * 与 docs/protocol.md §6 的表格一一对应，改动必须同步两边。
  */
 export const DEFAULT_PORTS = {
+    /**
+     * 本机 node agent（`@1agents/dreammate-node`）。**固定端口**，不可改：
+     * 它是整台机器对网络的唯一入口，外部节点靠"探 36908"找到这台机器上的一切。
+     */
+    "node-agent": 36908,
     "session-registry": 7777,
     "data-service": 7778,
     "control-plane": 7779,

package/docs/protocol.md

@@ -142,6 +142,7 @@ pull 要知道探哪儿，所以端口是公共词汇的一部分：
 
 | 端口 | Service | 层 |
 |------|---------|-----|
+| **36908** | **`node-agent`（dreammate-node）** | **本机基础设施** |
 | 7777 | `session-registry`（session-reader） | L2 |
 | 7778 | `data-service` | L2 |
 | 7779 | `control-plane` | L3 |
@@ -152,6 +153,61 @@ pull 要知道探哪儿，所以端口是公共词汇的一部分：
 得由它自己 `POST /nodes/register` 告知——register 因此是可选的加速/兜底，
 不是必需品。
 
+### 本机 node agent
+
+每台机器跑一个 `@1agents/dreammate-node`，固定监听 **36908**。它是这台机器
+对网络的唯一入口：
+
+```
+        Control Plane / 任意节点
+                  │  探 36908（每台机器只探一个端口）
+                  ▼
+        node-agent :36908
+         ├─ GET  /manifest      本机聚合视图：节点身份 + 所有已报备的服务
+         ├─ GET  /health
+         ├─ GET  /services      各服务的存活与可达性
+         └─ POST /services      服务报备（**仅接受 localhost**）
+                  ▲
+      ┌───────────┴───────────┐  localhost 报备
+ session-reader :7777    task-service :xxxx
+```
+
+这把 pull 探测的成本从「N 个节点 × M 个端口」降到「N × 1」。
+
+**报备是可选的。** 服务不报备也能工作，只是外部得靠约定端口才找得到它。
+报备时必须声明**可达性**：
+
+| `reachability` | 含义 |
+|---|---|
+| `localhost` | 只监听回环，外部节点发现得了但连不上 |
+| `network` | 监听 0.0.0.0 或 tailnet 地址，外部可直连 |
+
+agent 如实转述这个声明，**不做代理**。调用方看到 `localhost` 就知道这个能力
+只对本机开放，不用白跑一趟。
+
+> ⚠️ `POST /services` 只接受来自回环的请求。否则网络上任何人都能往你的节点
+> 里塞一个假服务，把调用方引到别处去。
+
+### Control Plane 不是一个进程
+
+node 注册与探活下沉成了每台机器的基础设施（就是上面的 agent），原本设想中
+Control Plane 的其余职责——Task、Agent 编排、Execution 账本——**降级为平级的
+普通服务**，各自独立起进程、各自向本机 agent 报备。
+
+```
+以前：Control Plane = Node Registry + Execution Ledger + Task + Orchestrator
+                      （一个大进程）
+
+现在：node-agent      = Node Registry + 探活        （每机一个，基础设施）
+      task-service    ┐
+      agent-service   ├ 平级服务，各自解耦运行，都向本机 agent 报备
+      execution-*     ┘
+```
+
+好处是任何一个服务挂掉都不会让整个控制面消失，也不存在"必须先起 Control Plane
+才能用"的启动顺序。代价是全网视图需要有人聚合——那也只是另一个服务，它靠
+tailnet + 探 36908 自己拼出来。
+
 ### 节点身份取自 tailnet
 
 节点的 `node_id` / `name` / `type` 应该直接用 tailnet 的事实，而不是自己生成：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/dreammate-network",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "DreamMate Network L0 协议包：schema + types，零运行时依赖，不含业务逻辑。",
   "keywords": [
     "dreammate",

package/schemas/service.schema.json

@@ -4,82 +4,165 @@
   "title": "DreamMate Service",
   "description": "Node 上的一组能力聚合。三层结构是 Node → Service → Capability / Resource，不要把 Capability 扁平铺到 Node 上。Agent Runtime 是 Service 的一种特殊 kind。",
   "type": "object",
-  "required": ["id", "capabilities"],
+  "required": [
+    "id",
+    "capabilities"
+  ],
   "properties": {
     "id": {
       "type": "string",
       "description": "Service 在所属 Node 内唯一。",
       "minLength": 1,
-      "examples": ["session-registry", "reminders", "recordings", "agent-runtime"]
+      "examples": [
+        "session-registry",
+        "reminders",
+        "recordings",
+        "agent-runtime"
+      ]
     },
     "name": {
-      "type": ["string", "null"],
+      "type": [
+        "string",
+        "null"
+      ],
       "description": "人类可读名称，可省略。"
     },
     "kind": {
       "type": "string",
       "description": "Service 类型。generic 之外的几种在传输层保留原生协议（见 protocol.md §5），不强行塞进 /capabilities/:name/invoke。",
-      "enum": ["generic", "agent_runtime", "session_registry", "resource_provider", "mcp"],
+      "enum": [
+        "generic",
+        "agent_runtime",
+        "session_registry",
+        "resource_provider",
+        "mcp"
+      ],
       "default": "generic"
     },
     "capabilities": {
       "type": "array",
       "description": "该 Service 能做什么。第一版就是点分命名的字符串，不带权限/可用性等元数据。可以为空数组（纯 Resource Provider）。",
-      "items": { "type": "string", "minLength": 1 },
-      "examples": [["sessions.list", "sessions.read"], ["reminders.create"], ["recordings.list", "recording.read"]]
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "examples": [
+        [
+          "sessions.list",
+          "sessions.read"
+        ],
+        [
+          "reminders.create"
+        ],
+        [
+          "recordings.list",
+          "recording.read"
+        ]
+      ]
     },
     "resources": {
       "type": "array",
       "description": "该 Service 拥有什么（可选，声明资源 URI 的 scheme 而非逐条枚举）。Capability=能做什么，Resource=拥有什么，两者不要混：检索侧走 resource.search/read，调度侧走 capability.invoke。",
       "items": {
         "type": "object",
-        "required": ["scheme"],
+        "required": [
+          "scheme"
+        ],
         "properties": {
           "scheme": {
             "type": "string",
             "description": "资源 URI 的 scheme。",
-            "examples": ["recording", "transcript", "speaker", "session"]
+            "examples": [
+              "recording",
+              "transcript",
+              "speaker",
+              "session"
+            ]
           },
-          "description": { "type": ["string", "null"] }
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
         }
       }
     },
     "access": {
       "type": "array",
       "description": "怎么访问这个 Service。传输方式只出现在这里，绝不进数据模型——不存在所谓 MCP Capability / CLI Capability。同一组能力可以同时有多种 access，调用方不必关心底层是谁。包装优先级 MCP > CLI > HTTP，但第一版不做自动 fallback 编排，手工声明即可。",
-      "items": { "$ref": "#/$defs/access" }
+      "items": {
+        "$ref": "#/$defs/access"
+      }
     },
     "metadata": {
       "type": "object",
       "description": "Service 级自由扩展字段。协议不解释其内容。",
       "additionalProperties": true
+    },
+    "reachability": {
+      "type": "string",
+      "enum": [
+        "localhost",
+        "network"
+      ],
+      "description": "这个 Service 能被谁连上。localhost=只监听回环，外部节点发现得了但连不上；network=监听 0.0.0.0 或 tailnet 地址，外部可直连。node agent 如实转述服务自己的声明，不做代理——调用方看到 localhost 就知道不用白跑一趟。省略时按 network 理解。"
+    },
+    "port": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "minimum": 1,
+      "maximum": 65535,
+      "description": "服务实际监听的端口。向本机 node agent 报备时带上，外部才知道该连哪儿；它不必等于 DEFAULT_PORTS 里的默认值。"
+    },
+    "health": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "存活探测路径，默认 /health。node agent 定期探它来判断服务死活——注意 Node 在线不代表 Service 在线。"
     }
   },
   "$defs": {
     "access": {
       "type": "object",
       "title": "Access Descriptor",
-      "required": ["protocol"],
+      "required": [
+        "protocol"
+      ],
       "properties": {
         "protocol": {
           "type": "string",
-          "enum": ["mcp", "http", "cli", "acp"],
+          "enum": [
+            "mcp",
+            "http",
+            "cli",
+            "acp"
+          ],
           "description": "acp 只用于 kind=agent_runtime 的 Session 控制，与前三者不是一回事：MCP/CLI/HTTP 面向 Capability / Resource，ACP 面向 Agent Runtime / Session Control。"
         },
         "base_url": {
           "type": "string",
           "description": "protocol=http 时的服务基址。",
-          "examples": ["http://scott-mac:7777/v1"]
+          "examples": [
+            "http://scott-mac:7777/v1"
+          ]
         },
         "endpoint": {
           "type": "string",
           "description": "protocol=http 时单个 capability 的相对路由。",
-          "examples": ["GET /transcripts/:id"]
+          "examples": [
+            "GET /transcripts/:id"
+          ]
         },
         "tool": {
           "type": "string",
           "description": "protocol=mcp 时对应的 tool 名。",
-          "examples": ["transcript_read"]
+          "examples": [
+            "transcript_read"
+          ]
         },
         "server": {
           "type": "string",
@@ -88,7 +171,10 @@
         "command": {
           "type": "string",
           "description": "protocol=cli 时的命令。",
-          "examples": ["tingqi transcript get", "1session overview"]
+          "examples": [
+            "tingqi transcript get",
+            "1session overview"
+          ]
         }
       }
     }
@@ -96,11 +182,22 @@
   "examples": [
     {
       "id": "transcripts",
-      "capabilities": ["transcript.read"],
+      "capabilities": [
+        "transcript.read"
+      ],
       "access": [
-        { "protocol": "mcp", "tool": "transcript_read" },
-        { "protocol": "http", "endpoint": "GET /transcripts/:id" },
-        { "protocol": "cli", "command": "tingqi transcript get" }
+        {
+          "protocol": "mcp",
+          "tool": "transcript_read"
+        },
+        {
+          "protocol": "http",
+          "endpoint": "GET /transcripts/:id"
+        },
+        {
+          "protocol": "cli",
+          "command": "tingqi transcript get"
+        }
       ]
     },
     {
@@ -113,7 +210,11 @@
         "agent.session.status",
         "agent.session.resume"
       ],
-      "access": [{ "protocol": "acp" }]
+      "access": [
+        {
+          "protocol": "acp"
+        }
+      ]
     }
   ]
 }