@mebular/fleet 0.0.0-stage → 0.1.0

package/dist/transport/spool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.js","sourceRoot":"","sources":["../../src/transport/spool.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,kCAAkC;AAElC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAI1C,MAAM,OAAO,cAAc;IACR,IAAI,CAAS;IAE9B,YAAY,QAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,MAAc;QAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IAEO,SAAS,CAAC,MAAc;QAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAqB;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC;QAChD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAwB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACnD,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE5C,MAAM,QAAQ,GAAmB,EAAE,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,IAAI,MAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAiB,CAAC;YACrE,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;gBACxC,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC;gBACvD,SAAS;YACX,CAAC;YACD,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,aAAa;IACf,CAAC;CACF"}

package/dist/transport/types.d.ts

@@ -0,0 +1,21 @@
+import type { FleetEndpoint } from '../protocol/envelope.js';
+import type { TaskEvent } from '../protocol/events.js';
+/** 传输消息：一次投递（可重复；`event.eventId` 为幂等键）。 */
+export interface FleetMessage {
+    /** 传输层消息 id（每次投递唯一，与 `event.eventId` 无关） */
+    msgId: string;
+    from: FleetEndpoint;
+    to: FleetEndpoint;
+    event: TaskEvent;
+}
+/** 设备间传输。`drain` 拉取并消费本端收件箱（已消费的不得再次返回；崩溃时允许重投）。 */
+export interface TaskTransport {
+    publish(message: FleetMessage): Promise<void>;
+    /**
+     * 拉取发往 `recipient` 的未消费消息（确定性顺序）；拉取后标记为已消费。
+     * 至少一次：崩溃可能重投，故消费方必须按 `event.eventId` 幂等。
+     */
+    drain(recipient: FleetEndpoint): Promise<FleetMessage[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,aAAa,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/transport/types.js

@@ -0,0 +1,6 @@
+// Fleet 传输抽象（M2 用本地 spool；M3 换 core 记忆同步，不改 runtime）。
+//
+// 传输层只负责把**显式状态事件**在设备间投递；语义（幂等、收敛）由 model.ts 负责。
+// 投递是**至少一次**：重复投递由 `eventId` 去重（见 PROTOCOL-INVARIANTS ①）。
+export {};
+//# sourceMappingURL=types.js.map

package/dist/transport/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,kDAAkD;AAClD,2DAA2D"}

package/dist/version.json

@@ -0,0 +1,6 @@
+{
+  "name": "@mebular/fleet",
+  "version": "0.1.0",
+  "sha": "38b7e436f79fe93d429d5fccc9a966c41b0a1f3d",
+  "builtAt": "2026-10-24T10:53:17.074Z"
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@mebular/fleet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Mebular 跨设备多 Agent 协作（任务=记忆）：task-as-memory 的派发与回收，无中心协调",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "fleet": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "protocol"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/chmod-bins.mjs && node ../../scripts/publish-manifest.mjs set",
+    "postpack": "node ../../scripts/publish-manifest.mjs restore"
+  },
+  "dependencies": {
+    "@mebular/core": "^0.1.0",
+    "@mebular/service": "^0.1.0",
+    "qrcode-generator": "2.0.4"
+  }
+}

package/protocol/collab.example.json

@@ -0,0 +1,23 @@
+{
+  "negotiation": {
+    "v": 1,
+    "messageId": "task-A#neg#1@device-B",
+    "taskId": "task-A",
+    "round": 1,
+    "from": { "device": "device-B", "agent": "worker" },
+    "kind": "counter",
+    "text": "need more detail"
+  },
+  "chatter": {
+    "v": 1,
+    "messageId": "chat-1@device-A",
+    "from": { "device": "device-A", "agent": "board" },
+    "topic": "status",
+    "text": "hello"
+  },
+  "dagPlan": {
+    "root": [{ "intent": "child-0" }, { "intent": "child-1" }],
+    "child-0": [],
+    "child-1": []
+  }
+}

package/protocol/daemon-home.example.json

@@ -0,0 +1,66 @@
+{
+  "note": "W2 一机一节点：统一 home 的守护 config 与 fleet 客户端 config 样例（identity/store 模式字段先行）。",
+  "daemonConfig": {
+    "storagePath": "~/.mebular/store.jsonl",
+    "deviceId": "device-A",
+    "identity": {
+      "mode": "root"
+    },
+    "encryption": {
+      "level": "none",
+      "keyFile": "~/.mebular/master-key.json"
+    },
+    "network": {
+      "enabled": true,
+      "libp2p": {
+        "listen": [
+          "/ip4/0.0.0.0/tcp/4001"
+        ]
+      }
+    },
+    "sync": {
+      "namespaces": [
+        "tasks"
+      ]
+    },
+    "joinService": {
+      "enabled": true,
+      "bind": "0.0.0.0",
+      "port": 4002
+    },
+    "mcp": {
+      "http": {
+        "host": "127.0.0.1",
+        "port": 7331,
+        "auth": "bearer",
+        "tokensFile": "~/.mebular/auth/tokens.json"
+      }
+    }
+  },
+  "delegatedDaemonConfig": {
+    "identity": {
+      "mode": "delegated"
+    },
+    "encryption": {
+      "level": "none",
+      "userMasterPublicKeyFile": "~/.mebular/user-master-key.json"
+    }
+  },
+  "fleetClientConfig": {
+    "store": "daemon",
+    "daemon": {
+      "endpoint": "http://127.0.0.1:7331",
+      "token": "meb_<secret>"
+    }
+  },
+  "modes": {
+    "identity": [
+      "root",
+      "delegated"
+    ],
+    "store": [
+      "daemon",
+      "embedded"
+    ]
+  }
+}

package/protocol/envelope.example.json

@@ -0,0 +1,12 @@
+{
+  "v": 1,
+  "taskId": "task-0001",
+  "from": { "device": "device-A", "agent": "planner" },
+  "to": { "device": "device-B", "agent": "*" },
+  "intent": "summarize",
+  "payloadRef": "node-abc123",
+  "status": "queued",
+  "attempts": 0,
+  "expiresAt": 1735689600000,
+  "trace": { "causedBy": "task-0000", "chain": ["task-0000"] }
+}

package/protocol/state-machine.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "statuses": ["queued", "claimed", "running", "done", "failed"],
+  "rank": { "queued": 0, "claimed": 1, "running": 2, "done": 3, "failed": 3 },
+  "terminal": ["done", "failed"],
+  "terminalPrecedence": { "queued": 0, "claimed": 0, "running": 0, "done": 1, "failed": 2 },
+  "transitions": {
+    "queued": ["claimed", "failed"],
+    "claimed": ["running", "failed"],
+    "running": ["done", "failed"],
+    "done": [],
+    "failed": []
+  }
+}

package/protocol/task-tree.example.json

@@ -0,0 +1,72 @@
+{
+  "v": 1,
+  "note": "W1 任务树夹具：root 声明预算与派发策略；子任务预算 ≤ 父剩余（越深越小）。",
+  "root": {
+    "v": 1,
+    "eventId": "task-A-root#created",
+    "taskId": "task-A-root",
+    "type": "created",
+    "actor": { "device": "device-A", "agent": "board" },
+    "at": 1700000000000,
+    "toStatus": "queued",
+    "trace": { "chain": [] },
+    "to": { "device": "device-B", "agent": "worker" },
+    "intent": "root",
+    "budget": { "maxDepth": 2, "maxChildren": 4, "maxTasks": 8 },
+    "dispatch": "children-ok"
+  },
+  "childWithinBudget": {
+    "v": 1,
+    "eventId": "task-A-root~c0#created",
+    "taskId": "task-A-root~c0",
+    "type": "created",
+    "actor": { "device": "device-B", "agent": "worker" },
+    "at": 1700000000001,
+    "toStatus": "queued",
+    "trace": { "causedBy": "task-A-root", "chain": ["task-A-root"] },
+    "to": { "device": "device-B", "agent": "worker" },
+    "intent": "child-0",
+    "budget": { "maxDepth": 1, "maxChildren": 4, "maxTasks": 7 }
+  },
+  "childOverBudget": {
+    "v": 1,
+    "eventId": "task-A-root~c1#created",
+    "taskId": "task-A-root~c1",
+    "type": "created",
+    "actor": { "device": "device-B", "agent": "worker" },
+    "at": 1700000000002,
+    "toStatus": "queued",
+    "trace": { "causedBy": "task-A-root", "chain": ["task-A-root"] },
+    "to": { "device": "device-B", "agent": "worker" },
+    "intent": "child-1",
+    "budget": { "maxDepth": 2, "maxChildren": 4, "maxTasks": 7 }
+  },
+  "rootOnlyChild": {
+    "v": 1,
+    "eventId": "task-A-ro#created",
+    "taskId": "task-A-ro~c0",
+    "type": "created",
+    "actor": { "device": "device-B", "agent": "worker" },
+    "at": 1700000000003,
+    "toStatus": "queued",
+    "trace": { "causedBy": "task-A-ro", "chain": ["task-A-ro"] },
+    "to": { "device": "device-B", "agent": "worker" },
+    "intent": "child",
+    "budget": { "maxDepth": 1, "maxChildren": 4, "maxTasks": 7 },
+    "note": "需与 rootOnlyRoot 同树；此处仅字段样例"
+  },
+  "rootOnlyRoot": {
+    "v": 1,
+    "eventId": "task-A-ro#created",
+    "taskId": "task-A-ro",
+    "type": "created",
+    "actor": { "device": "device-A", "agent": "board" },
+    "at": 1700000000003,
+    "toStatus": "queued",
+    "trace": { "chain": [] },
+    "to": { "device": "device-B", "agent": "worker" },
+    "intent": "root",
+    "budget": { "maxDepth": 3, "maxChildren": 4, "maxTasks": 8 },
+    "dispatch": "root-only"
+  }
+}

package/src/agentdir.ts

@@ -0,0 +1,138 @@
+// W1 每设备 Agent 目录（普通记忆域，默认 `agents`）。
+//
+// 每设备一条**签名**记录（作者=设备；随已有记忆同步，证书链由 core 校验）：
+//   { device, agents:[{name,kind,capabilities?,concurrency,capacity?}], updatedAt, version }
+// `task_targets` = **我 L1 授权过的对端** ∩ 其目录里的 `(device, agent)`。
+// `capacity`/`load` 为**建议性**（不参与授权与一致性判定）。
+
+import type { Mebular } from '@mebular/core';
+import { MebularMessageStore } from './store/message-store.js';
+
+export const AGENT_DIRECTORY_MESSAGE_TYPE = 'agent_directory';
+
+export interface AgentDirectoryAgent {
+  name: string;
+  /** 执行器 kind（与 `FleetAgentConfig.kind` 对齐：echo/command/hermes/openchamber） */
+  kind: string;
+  capabilities?: string[];
+  concurrency?: number;
+  /** 建议性容量提示（**不参与授权/一致性**） */
+  capacity?: number;
+}
+
+export interface AgentDirectoryEntry {
+  v: number;
+  device: string;
+  agents: AgentDirectoryAgent[];
+  /** 本机墙钟（**advisory**；不参与一致性判定） */
+  updatedAt: number;
+  /** 单调版本：同设备取最大者（R-c 式确定序，无墙钟） */
+  version: number;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export interface AgentDirectoryValidation {
+  ok: boolean;
+  errors: string[];
+}
+
+export function validateAgentDirectory(input: unknown): AgentDirectoryValidation {
+  const errors: string[] = [];
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) return { ok: false, errors: ['目录必须是对象'] };
+  const e = input as Record<string, unknown>;
+  if (e.v !== 1) errors.push('v 必须为 1');
+  if (!isNonEmptyString(e.device)) errors.push('device 必须为非空字符串');
+  if (typeof e.updatedAt !== 'number' || !Number.isFinite(e.updatedAt)) errors.push('updatedAt 必须为有限数字');
+  if (typeof e.version !== 'number' || !Number.isInteger(e.version) || e.version < 0) errors.push('version 必须为非负整数');
+  if (!Array.isArray(e.agents)) {
+    errors.push('agents 必须为数组');
+  } else {
+    for (const a of e.agents as Array<Record<string, unknown>>) {
+      if (!isNonEmptyString(a?.name)) errors.push('agent.name 必须为非空字符串');
+      if (!isNonEmptyString(a?.kind)) errors.push('agent.kind 必须为非空字符串');
+      if (a?.capabilities !== undefined && (!Array.isArray(a.capabilities) || a.capabilities.some((c) => typeof c !== 'string'))) {
+        errors.push('agent.capabilities 若存在须为字符串数组');
+      }
+      if (a?.concurrency !== undefined && (typeof a.concurrency !== 'number' || !Number.isInteger(a.concurrency) || a.concurrency < 1)) {
+        errors.push('agent.concurrency 若存在须为正整数');
+      }
+      if (a?.capacity !== undefined && (typeof a.capacity !== 'number' || !Number.isFinite(a.capacity) || a.capacity < 0)) {
+        errors.push('agent.capacity 若存在须为非负数字（advisory）');
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** 构造目录存储（校验 + 幂等键 `device@version`）。 */
+export function agentDirectoryStore(mebular: Mebular, namespace = 'agents'): MebularMessageStore<AgentDirectoryEntry> {
+  return new MebularMessageStore<AgentDirectoryEntry>(mebular, {
+    type: AGENT_DIRECTORY_MESSAGE_TYPE,
+    namespace,
+    validate: validateAgentDirectory,
+    idOf: (e) => `${e.device}@${e.version}`,
+  });
+}
+
+/** 每设备最新目录（同设备取 `version` 最大；平局取稳定序列化较大者，确定性）。 */
+export function latestDirectories(entries: readonly AgentDirectoryEntry[]): AgentDirectoryEntry[] {
+  const byDevice = new Map<string, AgentDirectoryEntry>();
+  for (const e of entries) {
+    const prev = byDevice.get(e.device);
+    if (prev === undefined) {
+      byDevice.set(e.device, e);
+      continue;
+    }
+    const stronger =
+      e.version !== prev.version
+        ? e.version > prev.version
+        : stable(e) > stable(prev);
+    if (stronger) byDevice.set(e.device, e);
+  }
+  return [...byDevice.values()].sort((a, b) => (a.device < b.device ? -1 : a.device > b.device ? 1 : 0));
+}
+
+function stable(value: unknown): string {
+  if (value === undefined) return 'null';
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  const rec = value as Record<string, unknown>;
+  return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${stable(rec[k])}`).join(',')}}`;
+}
+
+export interface TaskTarget {
+  device: string;
+  agent: string;
+  kind: string;
+  concurrency?: number;
+  capacity?: number;
+}
+
+/**
+ * `task_targets` = **L1 授权过的对端** ∩ 其目录里的 `(device, agent)`。
+ * 授权集合外的设备记录一律忽略（默认拒绝；授权是前提）。确定序（device, agent）。
+ */
+export function expandTargets(
+  entries: readonly AgentDirectoryEntry[],
+  authorizedDevices: readonly string[],
+): TaskTarget[] {
+  const allowed = new Set(authorizedDevices);
+  const targets: TaskTarget[] = [];
+  for (const entry of latestDirectories(entries)) {
+    if (!allowed.has(entry.device)) continue;
+    for (const agent of [...entry.agents].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      if (!isNonEmptyString(agent.name) || !isNonEmptyString(agent.kind)) continue;
+      targets.push({
+        device: entry.device,
+        agent: agent.name,
+        kind: agent.kind,
+        ...(agent.concurrency !== undefined ? { concurrency: agent.concurrency } : {}),
+        ...(agent.capacity !== undefined ? { capacity: agent.capacity } : {}),
+      });
+    }
+  }
+  return targets;
+}