@tool-bridge/server 0.5.0 → 0.10.0

package/dist/{chunk-3C3J36GT.js → chunk-Q7YHZ2SD.js}

@@ -2,6 +2,7 @@ import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
   DEFAULT_MAX_NODES,
+  DEVICE_CALL_TIMEOUT_MS,
   DeviceGatewaySession,
   FEEDBACK_HIDE_SCORE,
   FeedbackStore,
@@ -17,6 +18,12 @@ import {
   NEVER,
   NodeRegistryStore,
   OAUTH_CLIENT_FIELDS,
+  PG_SEARCH_INSERT_ROWS_MAX,
+  PG_SEARCH_SNAPSHOTS_COLUMNS,
+  PG_SEARCH_SNAPSHOTS_TABLE,
+  PG_SEARCH_TOOLS_COLUMNS,
+  PG_SEARCH_TOOLS_TABLE,
+  PG_SEARCH_WRITE_LOCK_KEY,
   PRESIGN_TTL_SEC_DEFAULT,
   RemoteAllowlistStore,
   SKILLHUB_CAPABILITIES,
@@ -68,6 +75,7 @@ import {
   createObjectContextProvider,
   createSkillhubProvider,
   decodeDeviceFrame,
+  derivePresence,
   deviceDirectoryHelpModel,
   deviceFsHelpModel,
   deviceShellHelpModel,
@@ -104,6 +112,8 @@ import {
   parseNodeInput,
   parseTokenResponse,
   parseVia,
+  pgBulkInsertSql,
+  pgSearchDialect,
   pluginTokenSecretName,
   preprocess,
   record,
@@ -130,7 +140,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-7PM4FD5K.js";
+} from "./chunk-TPGTA43F.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -149,7 +159,9 @@ function configFromEnv(env = process.env) {
   const allowInsecure = env.TB_ALLOW_INSECURE_HTTP === "true";
   const allowlist = (env.TB_REMOTE_ALLOWLIST ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
   const config = {
-    port: portEnv(env.TB_PORT) ?? DEFAULT_PORT,
+    // TB_PORT 优先,PORT 兜底:Railway / Fly / Cloud Run / CF Container 等 PaaS 只注入
+    // PORT,不认识 TB_PORT —— 不兜底的话容器会监听 8787 而平台探活另一个端口,部署直接失败。
+    port: portEnv(env.TB_PORT) ?? portEnv(env.PORT) ?? DEFAULT_PORT,
     host: env.TB_HOST !== void 0 && env.TB_HOST.length > 0 ? env.TB_HOST : "0.0.0.0",
     dataDir: env.TB_DATA_DIR !== void 0 && env.TB_DATA_DIR.length > 0 ? env.TB_DATA_DIR : "./data",
     allowInsecureHttp: allowInsecure,
@@ -160,9 +172,45 @@ function configFromEnv(env = process.env) {
       ...env.TB_INSTANCE_ID !== void 0 && env.TB_INSTANCE_ID.length > 0 ? { instanceId: env.TB_INSTANCE_ID } : {},
       allowInsecure
     },
-    deviceReclaimSec: positiveIntEnv(env.TB_DEVICE_RECLAIM_SEC) ?? DEFAULT_DEVICE_RECLAIM_SEC
+    deviceReclaimSec: positiveIntEnv(env.TB_DEVICE_RECLAIM_SEC) ?? DEFAULT_DEVICE_RECLAIM_SEC,
+    // 0 合法(立即关停,本地/单机默认);positiveIntEnv 拒 0,故单独解析。
+    shutdownDrainSec: (() => {
+      const n = Number(env.TB_SHUTDOWN_DRAIN_SEC);
+      return Number.isInteger(n) && n >= 0 ? n : 0;
+    })()
   };
   if (env.TB_UI_DIR !== void 0 && env.TB_UI_DIR.length > 0) config.uiDir = env.TB_UI_DIR;
+  if (env.TB_DATABASE_URL !== void 0 && env.TB_DATABASE_URL.length > 0) {
+    config.databaseUrl = env.TB_DATABASE_URL;
+  }
+  if (env.TB_REDIS_URL !== void 0 && env.TB_REDIS_URL.length > 0) {
+    config.redisUrl = env.TB_REDIS_URL;
+  }
+  if (env.TB_REPLICA_ID !== void 0 && env.TB_REPLICA_ID.length > 0) {
+    config.replicaId = env.TB_REPLICA_ID;
+  }
+  const s3Vars = [
+    ["TB_OBJECT_STORE_ENDPOINT", env.TB_OBJECT_STORE_ENDPOINT],
+    ["TB_OBJECT_STORE_BUCKET", env.TB_OBJECT_STORE_BUCKET],
+    ["TB_OBJECT_STORE_ACCESS_KEY_ID", env.TB_OBJECT_STORE_ACCESS_KEY_ID],
+    ["TB_OBJECT_STORE_SECRET_ACCESS_KEY", env.TB_OBJECT_STORE_SECRET_ACCESS_KEY]
+  ];
+  const present = s3Vars.filter(([, value]) => value !== void 0 && value.length > 0);
+  if (present.length > 0) {
+    if (present.length < s3Vars.length) {
+      const missing = s3Vars.filter(([, value]) => value === void 0 || value.length === 0).map(([name]) => name);
+      throw new Error(
+        `\u5E73\u53F0\u5BF9\u8C61\u5B58\u50A8\u914D\u7F6E\u4E0D\u5B8C\u6574(\u7ED9\u4E86 ${present.length}/${s3Vars.length} \u9879),\u7F3A\u5C11:${missing.join(", ")}`
+      );
+    }
+    config.objectStore = {
+      accessKeyId: env.TB_OBJECT_STORE_ACCESS_KEY_ID,
+      bucket: env.TB_OBJECT_STORE_BUCKET,
+      endpoint: env.TB_OBJECT_STORE_ENDPOINT,
+      secretAccessKey: env.TB_OBJECT_STORE_SECRET_ACCESS_KEY,
+      ...env.TB_OBJECT_STORE_REGION !== void 0 && env.TB_OBJECT_STORE_REGION.length > 0 ? { region: env.TB_OBJECT_STORE_REGION } : {}
+    };
+  }
   if (env.TB_BOOTSTRAP_ADMIN_SK !== void 0 && env.TB_BOOTSTRAP_ADMIN_SK.length > 0) {
     config.adminSk = env.TB_BOOTSTRAP_ADMIN_SK;
   }
@@ -394,8 +442,15 @@ var BUILTIN_DESCRIPTIONS = {
 async function mintAdminWithPlaintext(store, plaintext, now) {
   const { key } = await mintKey(adminBootstrapInput(), now);
   const adminKey = { ...key, hash: await sha256Hex(plaintext) };
-  await store.put(KEY_SK_HASH + adminKey.hash, adminKey);
-  await store.put(KEY_SK_ID + adminKey.id, adminKey.hash);
+  const hashKey = KEY_SK_HASH + adminKey.hash;
+  let won;
+  if (store.putIfAbsent !== void 0) {
+    won = await store.putIfAbsent(hashKey, adminKey);
+  } else {
+    won = await store.get(hashKey) === null;
+    if (won) await store.put(hashKey, adminKey);
+  }
+  if (won) await store.put(KEY_SK_ID + adminKey.id, adminKey.hash);
 }
 async function ensureBuiltinNodes(registry, now) {
   const ensure = async (node) => {
@@ -963,6 +1018,15 @@ async function invokeDevice(deps, deviceId, req) {
   if (body.ok) return body.value;
   throw tbErrorFromBody(body.error);
 }
+function deviceCallContextFrom(ctx) {
+  const now = Date.now();
+  return {
+    caller: { keyId: ctx.keyId, owner: ctx.owner },
+    traceId: ctx.traceId,
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + DEVICE_CALL_TIMEOUT_MS).toISOString()
+  };
+}
 function deviceMarkerOf(pc) {
   if (pc === void 0 || typeof pc.deviceId !== "string" || typeof pc.mountPath !== "string") {
     return null;
@@ -14197,8 +14261,8 @@ function applyPostAuth(clientId, clientSecret, params) {
 function applyPublicAuth(clientId, params) {
   params.set("client_id", clientId);
 }
-function isLoopbackHost(hostname) {
-  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+function isLoopbackHost(hostname2) {
+  return hostname2 === "localhost" || hostname2 === "127.0.0.1" || hostname2 === "[::1]" || hostname2 === "::1";
 }
 function assertSecureTokenEndpoint(tokenEndpoint) {
   const url2 = new URL(String(tokenEndpoint));
@@ -19922,7 +19986,7 @@ async function processDeviceHello(opts) {
         input,
         authCtx.keyId,
         now,
-        input.path === mountPath ? { online: true } : {}
+        input.path === mountPath ? { online: true, lastSeenAt: now } : {}
       );
     } catch (error) {
       await searchSync?.abort(marker);
@@ -19932,8 +19996,8 @@ async function processDeviceHello(opts) {
       throw error;
     }
   }
-  await searchSync?.rebuildAll(searchMarkers);
-  return { mountPath, keyId: authCtx.keyId };
+  const searchIndexed = searchSync === void 0 ? true : await searchSync.rebuildAll(searchMarkers);
+  return { mountPath, keyId: authCtx.keyId, searchIndexed };
 }
 
 // ../../node_modules/.pnpm/@modelcontextprotocol+server@2.0.0/node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
@@ -35898,9 +35962,15 @@ async function assertRegisterPath2(registry, ctx, targetPath, action, deps) {
   });
   if (!res.allow) throw res.error;
 }
-function toEntry(n) {
+function toEntry(n, now) {
   const e = { path: n.path, kind: n.kind, description: n.description };
-  if (n.online !== void 0) e.online = n.online;
+  if (n.online !== void 0) {
+    e.presence = derivePresence({
+      online: n.online,
+      ...n.lastSeenAt !== void 0 ? { lastSeenAt: n.lastSeenAt } : {},
+      now
+    });
+  }
   return e;
 }
 function filterListVisible(nodes, scopes) {
@@ -36156,7 +36226,7 @@ function localizeRemoteEntry(mountPath, remoteParentPath, entry) {
     kind: entry.kind,
     description: entry.description
   };
-  if (entry.online !== void 0) out.online = entry.online;
+  if (entry.presence !== void 0) out.presence = entry.presence;
   return out;
 }
 async function resolveRemoteSettings(state, base) {
@@ -36460,6 +36530,17 @@ function registerPublicRoutes(app, env) {
       ...catalog !== void 0 && digest !== void 0 ? { catalog: { count: Object.keys(catalog).length, digest } } : {}
     });
   });
+  app.get("/livez", (c) => c.json({ live: true }));
+  app.get("/readyz", async (c) => {
+    const probe = deps.readiness;
+    if (probe === void 0) return c.json({ checks: {}, ready: true });
+    try {
+      const report = await probe();
+      return c.json(report, report.ready ? 200 : 503);
+    } catch {
+      return c.json({ checks: {}, ready: false }, 503);
+    }
+  });
   app.get(
     "/~ref/:token",
     (c) => runHandler(async () => {
@@ -36699,6 +36780,7 @@ function registerSearchRoute(app, env) {
 
 // ../app/src/helpModel.ts
 async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
+  const index = opts.schemas !== true;
   if (node.kind === "builtin" && node.config?.kind === "builtin") {
     const mod = builtins.get(node.config.module);
     if (mod) return mod.help(node.path);
@@ -36710,8 +36792,13 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
       ctx.scopes
     );
     if (node.online !== void 0) {
+      const presence = derivePresence({
+        online: node.online,
+        ...node.lastSeenAt !== void 0 ? { lastSeenAt: node.lastSeenAt } : {},
+        now: opts.now
+      });
       return deviceDirectoryHelpModel(
-        { path: node.path, description: node.description, online: node.online },
+        { path: node.path, description: node.description, presence },
         children.map((n) => ({ path: n.path, kind: n.kind, description: n.description }))
       );
     }
@@ -36728,7 +36815,7 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
       node.path,
       { kind: node.kind, description: node.description },
       toolMarker.cmds ?? [],
-      { index: true }
+      { index }
     );
   }
   if (node.kind === "mcp" || node.kind === "http" || node.kind === "tool") {
@@ -36739,9 +36826,7 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
       node.path,
       { kind: node.kind, description: node.description },
       exposed,
-      {
-        index: true
-      }
+      { index }
     );
   }
   if (node.kind === "device" && node.config?.kind === "device") {
@@ -37207,7 +37292,8 @@ async function handleInvoke(c, env) {
     const result2 = await invokeDevice(deps, toolMarker.deviceId, {
       path: relativeDevicePath(node.path, toolMarker.mountPath),
       tool,
-      arguments: args2
+      arguments: args2,
+      context: deviceCallContextFrom(ctx)
     });
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
@@ -37236,7 +37322,8 @@ async function handleInvoke(c, env) {
     const result2 = await invokeDevice(deps, node.config.deviceId, {
       path: "shell",
       tool: body2.tool,
-      arguments: body2.arguments ?? {}
+      arguments: body2.arguments ?? {},
+      context: deviceCallContextFrom(ctx)
     });
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
@@ -37262,7 +37349,8 @@ async function handleInvoke(c, env) {
       const result3 = await invokeDevice(deps, deviceIdForDeviceFs(cfg), {
         path: "fs",
         tool: body2.tool,
-        arguments: args2
+        arguments: args2,
+        context: deviceCallContextFrom(ctx)
       });
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
@@ -37271,7 +37359,8 @@ async function handleInvoke(c, env) {
       const result3 = await invokeDevice(deps, contextMarker.deviceId, {
         path: relativeDevicePath(node.path, contextMarker.mountPath),
         tool: body2.tool,
-        arguments: args2
+        arguments: args2,
+        context: deviceCallContextFrom(ctx)
       });
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
@@ -37497,8 +37586,10 @@ async function handleHelp(c, env) {
   }
   const builtins = builtinsOf(store);
   const refresh = c.req.query("refresh") === "1";
+  const schemas = c.req.query("schemas") === "1";
   const model = await helpModelFor(node, registry, ctx, builtins, deps, {
     refresh,
+    schemas,
     now: (/* @__PURE__ */ new Date()).toISOString()
   });
   return renderHelp(await enrichHelp(model, path, store), rep);
@@ -37514,6 +37605,7 @@ async function handleTree(c, env) {
   const store = c.get("store");
   if (path !== "" && !check(ctx, path, "read").allow) throw TBError.notFound("not found");
   const registry = new NodeRegistryStore(store);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
   if (path !== "") {
     const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~tree", deps);
     if (remote) return remote;
@@ -37529,14 +37621,14 @@ async function handleTree(c, env) {
     if (rootNode.kind === "context" && rootNode.config?.kind === "context") {
       await assertContextAlive(rootNode, rootNode.config, registry);
     }
-    rootEntry = toEntry(rootNode);
+    rootEntry = toEntry(rootNode, now);
   }
   const nodes = await pruneExpiredContext(await registry.subtree(path), registry);
   const byParent = indexByParent(nodes);
   const getChildren = async (p) => {
     const localKids = filterListVisible(byParent.get(p) ?? [], ctx.scopes);
     const remoteKids = await remoteTreeChildren(c, ctx, registry, p, deps);
-    return [...localKids.map((n) => toEntry(n)), ...remoteKids];
+    return [...localKids.map((n) => toEntry(n, now)), ...remoteKids];
   };
   const depth = clampDepth(Number(c.req.query("depth")));
   const tree = await buildTree({
@@ -37683,14 +37775,26 @@ var DeviceHub = class {
   connections = /* @__PURE__ */ new Set();
   reclaimTimers = /* @__PURE__ */ new Map();
   heartbeat;
+  /** 多副本路由;缺省(单副本)时所有跨副本逻辑短路,行为与之前完全一致。 */
+  router;
   constructor(opts) {
     this.store = opts.store;
     this.search = opts.search;
     this.reclaimSec = opts.reclaimSec;
+    this.router = opts.router?.(
+      async (deviceId, req) => await this.invokeLocal(deviceId, req)
+    );
     const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
     this.heartbeat = setInterval(() => this.pingConnections(), heartbeatMs);
     this.heartbeat.unref?.();
   }
+  /**
+   * 启动多副本路由(订阅本副本频道 + 路由续期)。单副本时是 no-op。
+   * 必须在开始服务前完成:订阅没建好时转发进来的调用会丢。
+   */
+  async startRouter() {
+    await this.router?.start();
+  }
   /** 挂到 http.Server 的 'upgrade' 事件(仅处理 DEVICE_WS_PATH,其余 404)。 */
   attach(server) {
     server.on("upgrade", (req, socket, head) => {
@@ -37702,8 +37806,26 @@ var DeviceHub = class {
       });
     });
   }
-  /** DeviceChannel.invoke:HTTP→WS 调用转发(无活连接 → deviceOffline)。 */
+  /**
+   * DeviceChannel.invoke:HTTP→WS 调用转发。
+   *
+   * 本副本持有该设备 → 直接走本地 socket(单副本部署恒走这条,零额外开销)。
+   * 本地没有但配了 router → 问路由表并转发给持有者副本(socket 不可序列化,
+   * 只能把调用送到 socket 所在进程)。都没有 → deviceOffline。
+   */
   async invoke(deviceId, req) {
+    if (this.activeByDevice.has(deviceId)) return await this.invokeLocal(deviceId, req);
+    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    if (this.router === void 0) return offline;
+    return await this.router.forward(deviceId, req) ?? offline;
+  }
+  /**
+   * 只走本副本 socket 的调用执行。
+   *
+   * router 收到转发来的调用时回调这里 —— **不能**回调 `invoke`:本地连接刚断时
+   * 那会再次查路由并转发,在两个副本间弹来弹去。这里没有连接就直接 offline。
+   */
+  async invokeLocal(deviceId, req) {
     const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
     const conn = this.activeByDevice.get(deviceId);
     if (conn === void 0) return offline;
@@ -37741,8 +37863,15 @@ var DeviceHub = class {
         if (!isDeviceMeta(item.value)) continue;
         const meta = item.value;
         if (this.activeByDevice.has(meta.deviceId)) continue;
+        if (this.router !== void 0 && await this.router.isOnlineAnywhere(meta.deviceId)) {
+          continue;
+        }
         if (meta.disconnectedAt === void 0) {
           const now = (/* @__PURE__ */ new Date()).toISOString();
+          try {
+            await new NodeRegistryStore(this.store).setOnline(meta.mountPath, false, now);
+          } catch {
+          }
           await this.store.put(KEY_DEVICE_META + meta.deviceId, { ...meta, disconnectedAt: now });
           this.scheduleReclaim(meta.deviceId, this.reclaimSec * 1e3);
         } else {
@@ -37762,6 +37891,10 @@ var DeviceHub = class {
     for (const conn of this.connections) conn.ws.terminate();
     this.connections.clear();
     this.activeByDevice.clear();
+    const router = this.router;
+    this.router = void 0;
+    await router?.close().catch(() => {
+    });
     await new Promise((resolve3) => this.wss.close(() => resolve3()));
   }
   async handleUpgrade(req, socket, head) {
@@ -37807,6 +37940,10 @@ var DeviceHub = class {
     this.connections.add(conn);
     ws.on("pong", () => {
       conn.isAlive = true;
+      if (conn.mountPath !== void 0) {
+        void new NodeRegistryStore(this.store).touchSeen(conn.mountPath, (/* @__PURE__ */ new Date()).toISOString()).catch(() => {
+        });
+      }
     });
     ws.on("message", (data) => {
       try {
@@ -37823,7 +37960,7 @@ var DeviceHub = class {
   }
   async acceptHello(conn, hello) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const { mountPath, keyId } = await processDeviceHello({
+    const { mountPath, keyId, searchIndexed } = await processDeviceHello({
       store: this.store,
       authorization: conn.authorization,
       deviceIdHint: conn.deviceId,
@@ -37831,6 +37968,11 @@ var DeviceHub = class {
       now,
       ...this.search === void 0 ? {} : { search: this.search }
     });
+    if (!searchIndexed) {
+      console.warn(
+        `[tool-bridge] device '${conn.deviceId}' mounted at ${mountPath} but its tools are NOT in the search index: registry exceeds the tool-search capacity (TOOL_SEARCH_AUDIT_NODE_LIMIT). The device is callable but won't appear in \`tb search\` until capacity frees up.`
+      );
+    }
     const meta = { deviceId: conn.deviceId, mountPath, keyId, connectedAt: now };
     await this.store.put(KEY_DEVICE_META + conn.deviceId, meta);
     conn.keyId = keyId;
@@ -37839,6 +37981,8 @@ var DeviceHub = class {
     const prev = this.activeByDevice.get(conn.deviceId);
     if (prev !== void 0 && prev !== conn) prev.ws.close(1e3, "replaced");
     this.activeByDevice.set(conn.deviceId, conn);
+    await this.router?.claim(conn.deviceId).catch(() => {
+    });
     conn.session.accept(mountPath);
   }
   /** 连接失效收尾(对位 DO markDisconnected):registry 下线 + meta 记断线 + 排回收。 */
@@ -37847,6 +37991,8 @@ var DeviceHub = class {
     this.connections.delete(conn);
     if (this.activeByDevice.get(conn.deviceId) !== conn) return;
     this.activeByDevice.delete(conn.deviceId);
+    await this.router?.release(conn.deviceId).catch(() => {
+    });
     const raw = await this.store.get(KEY_DEVICE_META + conn.deviceId);
     if (!isDeviceMeta(raw)) return;
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -37877,6 +38023,13 @@ var DeviceHub = class {
   async reclaim(deviceId) {
     this.reclaimTimers.delete(deviceId);
     if (this.activeByDevice.has(deviceId)) return;
+    if (this.router !== void 0) {
+      try {
+        if (await this.router.isOnlineAnywhere(deviceId)) return;
+      } catch {
+        return;
+      }
+    }
     const raw = await this.store.get(KEY_DEVICE_META + deviceId);
     if (!isDeviceMeta(raw)) return;
     const searchSync = this.search === void 0 ? void 0 : new SearchSynchronizer(this.store, this.search);
@@ -37901,6 +38054,146 @@ var DeviceHub = class {
   }
 };
 
+// src/deviceRouter.ts
+var DEVICE_ROUTE_TTL_SEC = 30;
+var DEVICE_FORWARD_TIMEOUT_MS = 65e3;
+var deviceRouteKey = (deviceId) => `tb:device:route:${deviceId}`;
+var deviceCallChannel = (replicaId) => `tb:device:call:${replicaId}`;
+var deviceReplyChannel = (replicaId) => `tb:device:reply:${replicaId}`;
+var DeviceRouter = class _DeviceRouter {
+  constructor(replicaId, backend, opts) {
+    this.replicaId = replicaId;
+    this.backend = backend;
+    this.opts = opts;
+  }
+  replicaId;
+  backend;
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  renewTimer;
+  /** 本副本当前持有的设备(需周期续期路由条目)。 */
+  owned = /* @__PURE__ */ new Set();
+  get ttlSec() {
+    return this.opts.ttlSec ?? DEVICE_ROUTE_TTL_SEC;
+  }
+  /** 订阅本副本的两个频道并启动路由续期。 */
+  async start() {
+    await this.backend.subscribe(deviceCallChannel(this.replicaId), (payload) => {
+      void this.handleForwardedCall(payload);
+    });
+    await this.backend.subscribe(deviceReplyChannel(this.replicaId), (payload) => {
+      this.handleReply(payload);
+    });
+    const renewMs = Math.max(1e3, Math.floor(this.ttlSec * 1e3 / 3));
+    this.renewTimer = setInterval(() => {
+      void this.renewOwned();
+    }, renewMs);
+    this.renewTimer.unref?.();
+  }
+  /** 本副本接受了某设备的连接:声明所有权。 */
+  async claim(deviceId) {
+    this.owned.add(deviceId);
+    await this.backend.setRoute(deviceId, this.replicaId, this.ttlSec);
+  }
+  /** 本副本失去某设备的连接:释放所有权。 */
+  async release(deviceId) {
+    this.owned.delete(deviceId);
+    await this.backend.clearRoute(deviceId, this.replicaId);
+  }
+  /** 某设备当前是否在**任一**副本上在线(reclaim 判定用,不能只看本副本)。 */
+  async isOnlineAnywhere(deviceId) {
+    return await this.backend.lookupRoute(deviceId) !== null;
+  }
+  /**
+   * 把调用转发给持有该设备的副本并等结果。
+   * 无人持有 → null(调用方按 deviceOffline 处理)。
+   */
+  async forward(deviceId, req) {
+    const owner = await this.backend.lookupRoute(deviceId);
+    if (owner === null) return null;
+    if (owner === this.replicaId) return null;
+    const correlationId = `${this.replicaId}:${deviceId}:${++_DeviceRouter.seq}`;
+    const call = {
+      correlationId,
+      deviceId,
+      replyTo: this.replicaId,
+      req
+    };
+    return await new Promise((resolve3) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(correlationId);
+        resolve3({ ok: false, error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u8D85\u65F6").toJSON() });
+      }, this.opts.forwardTimeoutMs ?? DEVICE_FORWARD_TIMEOUT_MS);
+      timer.unref?.();
+      this.pending.set(correlationId, { resolve: resolve3, timer });
+      void this.backend.publish(deviceCallChannel(owner), JSON.stringify(call)).catch(() => {
+        const waiter = this.pending.get(correlationId);
+        if (waiter === void 0) return;
+        this.pending.delete(correlationId);
+        clearTimeout(waiter.timer);
+        waiter.resolve({
+          ok: false,
+          error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+        });
+      });
+    });
+  }
+  async close() {
+    if (this.renewTimer !== void 0) clearInterval(this.renewTimer);
+    this.renewTimer = void 0;
+    for (const [, waiter] of this.pending) {
+      clearTimeout(waiter.timer);
+      waiter.resolve({ ok: false, error: new TBError("unavailable", "\u7F51\u5173\u6B63\u5728\u5173\u95ED").toJSON() });
+    }
+    this.pending.clear();
+    await Promise.all([...this.owned].map(async (id) => await this.release(id)));
+    await this.backend.close();
+  }
+  /** correlationId 的进程内序号(与 replicaId 组合后全局唯一)。 */
+  static seq = 0;
+  async renewOwned() {
+    for (const deviceId of this.owned) {
+      try {
+        await this.backend.setRoute(deviceId, this.replicaId, this.ttlSec);
+      } catch {
+      }
+    }
+  }
+  /** 作为持有者:执行本地调用并回执。 */
+  async handleForwardedCall(payload) {
+    let call;
+    try {
+      call = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (typeof call?.correlationId !== "string" || typeof call?.replyTo !== "string") return;
+    let result;
+    try {
+      result = await this.opts.onLocalCall(call.deviceId, call.req);
+    } catch {
+      result = { ok: false, error: new TBError("internal", "\u8BBE\u5907\u8C03\u7528\u6267\u884C\u5931\u8D25").toJSON() };
+    }
+    const reply = { correlationId: call.correlationId, result };
+    await this.backend.publish(deviceReplyChannel(call.replyTo), JSON.stringify(reply)).catch(() => {
+    });
+  }
+  /** 作为发起方:收到回执,唤醒等待者。 */
+  handleReply(payload) {
+    let reply;
+    try {
+      reply = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    const waiter = this.pending.get(reply?.correlationId);
+    if (waiter === void 0) return;
+    this.pending.delete(reply.correlationId);
+    clearTimeout(waiter.timer);
+    waiter.resolve(reply.result);
+  }
+};
+
 // ../core/src/node/fsObjectStore.ts
 import { mkdir, readdir, readFile, realpath, rm, stat, writeFile } from "fs/promises";
 import { basename, dirname, join, resolve, sep } from "path";
@@ -38185,6 +38478,219 @@ function createDataObjectStore(dataDir) {
   };
 }
 
+// src/pgSearchIndex.ts
+var PgSearchDriver = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  schemaReady;
+  async all(statement) {
+    return await this.sql.unsafe(statement.sql, statement.params);
+  }
+  async initializeSchema() {
+    try {
+      await this.sql.begin(async (tx) => {
+        for (const ddl of pgSearchDialect.schemaStatements) {
+          await tx.unsafe(ddl);
+        }
+      });
+    } catch (error) {
+      this.schemaReady = void 0;
+      throw error;
+    }
+  }
+  ensureSchema() {
+    this.schemaReady ??= this.initializeSchema();
+    return this.schemaReady;
+  }
+  async first(statement) {
+    const rows = await this.sql.unsafe(statement.sql, statement.params);
+    return rows[0] ?? null;
+  }
+  /**
+   * 攒成多行 VALUES 批量插入,而非逐条。
+   * 逐条对 4000 行需 ~920ms(每行一次事务内往返),批量后 ~12ms。
+   */
+  bulk(items, table, columns, toParams) {
+    const statements = [];
+    for (let i = 0; i < items.length; i += PG_SEARCH_INSERT_ROWS_MAX) {
+      const chunk = items.slice(i, i + PG_SEARCH_INSERT_ROWS_MAX);
+      statements.push({
+        params: chunk.flatMap(toParams),
+        sql: pgBulkInsertSql(table, columns, chunk.length)
+      });
+    }
+    return statements;
+  }
+  insertRecords(records) {
+    return this.bulk(
+      records,
+      PG_SEARCH_TOOLS_TABLE,
+      PG_SEARCH_TOOLS_COLUMNS,
+      (record2) => [record2.path, record2.name, record2.description, record2.feedback]
+    );
+  }
+  insertSnapshots(digests) {
+    return this.bulk(
+      [...digests],
+      PG_SEARCH_SNAPSHOTS_TABLE,
+      PG_SEARCH_SNAPSHOTS_COLUMNS,
+      ([path, digest]) => [path, digest]
+    );
+  }
+  async write(statements) {
+    await this.sql.begin(async (tx) => {
+      await tx`SELECT pg_advisory_xact_lock(${PG_SEARCH_WRITE_LOCK_KEY})`;
+      for (const statement of statements) {
+        await tx.unsafe(statement.sql, statement.params);
+      }
+    });
+  }
+};
+var PgSearchIndex = class extends SqlSearchIndex {
+  constructor(sql) {
+    super(new PgSearchDriver(sql), pgSearchDialect);
+  }
+};
+
+// src/pgStateStore.ts
+var DEFAULT_LIST_LIMIT = 1e3;
+var MAX_CODE_POINT = 1114111;
+var SURROGATE_START = 55296;
+var SURROGATE_END = 57343;
+function prefixUpperBound(prefix) {
+  const points = [...prefix];
+  for (let i = points.length - 1; i >= 0; i--) {
+    const code = points[i]?.codePointAt(0);
+    if (code === void 0 || code >= MAX_CODE_POINT) continue;
+    let next = code + 1;
+    if (next >= SURROGATE_START && next <= SURROGATE_END) next = SURROGATE_END + 1;
+    return points.slice(0, i).join("") + String.fromCodePoint(next);
+  }
+  return void 0;
+}
+var PgStateStore = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  /** 建表(幂等)。key COLLATE "C" 是字节序正确性的前提,不能省。 */
+  async ensureSchema() {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS tb_kv (
+        key text COLLATE "C" PRIMARY KEY,
+        value jsonb NOT NULL
+      )
+    `;
+  }
+  async get(key) {
+    const rows = await this.sql`
+      SELECT value FROM tb_kv WHERE key = ${key}
+    `;
+    const row = rows[0];
+    return row === void 0 ? null : row.value;
+  }
+  async getMany(keys) {
+    const unique = [...new Set(keys)];
+    if (unique.length === 0) return /* @__PURE__ */ new Map();
+    const rows = await this.sql`
+      SELECT key, value FROM tb_kv WHERE key = ANY(${this.sql.array(unique)})
+    `;
+    const byKey = new Map(rows.map((row) => [row.key, row.value]));
+    const out = /* @__PURE__ */ new Map();
+    for (const key of unique) {
+      if (byKey.has(key)) out.set(key, byKey.get(key));
+    }
+    return out;
+  }
+  async put(key, value) {
+    await this.sql`
+      INSERT INTO tb_kv (key, value) VALUES (${key}, ${this.sql.json(value)})
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value
+    `;
+  }
+  async putIfAbsent(key, value) {
+    const result = await this.sql`
+      INSERT INTO tb_kv (key, value) VALUES (${key}, ${this.sql.json(value)})
+      ON CONFLICT (key) DO NOTHING
+    `;
+    return result.count > 0;
+  }
+  async delete(key) {
+    await this.sql`DELETE FROM tb_kv WHERE key = ${key}`;
+  }
+  async list(prefix, opts) {
+    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT;
+    const lowerByCursor = opts?.cursor !== void 0 && opts.cursor >= prefix;
+    const upper = prefix === "" ? void 0 : prefixUpperBound(prefix);
+    const rows = await this.sql`
+      SELECT key, value FROM tb_kv
+      WHERE ${lowerByCursor ? this.sql`key > ${opts?.cursor ?? ""}` : this.sql`key >= ${prefix}`}
+      ${upper !== void 0 ? this.sql`AND key < ${upper}` : this.sql``}
+      ORDER BY key
+      LIMIT ${limit + 1}
+    `;
+    const matched = rows.filter((r) => r.key.startsWith(prefix));
+    const hasMore = matched.length > limit;
+    const page = hasMore ? matched.slice(0, limit) : matched;
+    const items = page.map((r) => ({ key: r.key, value: r.value }));
+    const last = page[page.length - 1];
+    return hasMore && last !== void 0 ? { items, cursor: last.key } : { items };
+  }
+};
+
+// src/redisDeviceRouter.ts
+import { Redis } from "ioredis";
+var CLEAR_IF_OWNER = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+end
+return 0
+`;
+var RedisDeviceRouterBackend = class {
+  /** 命令连接(GET/SET/DEL/PUBLISH)。 */
+  commands;
+  /** 订阅连接(进入 subscribe 模式后不能发普通命令)。 */
+  subscriber;
+  handlers = /* @__PURE__ */ new Map();
+  constructor(url2) {
+    this.commands = new Redis(url2, { maxRetriesPerRequest: 2 });
+    this.subscriber = new Redis(url2, { maxRetriesPerRequest: 2 });
+    this.subscriber.on("message", (channel, payload) => {
+      this.handlers.get(channel)?.(payload);
+    });
+    this.commands.on("error", () => {
+    });
+    this.subscriber.on("error", () => {
+    });
+  }
+  async setRoute(deviceId, replicaId, ttlSec) {
+    await this.commands.set(deviceRouteKey(deviceId), replicaId, "EX", ttlSec);
+  }
+  async lookupRoute(deviceId) {
+    return await this.commands.get(deviceRouteKey(deviceId));
+  }
+  async clearRoute(deviceId, replicaId) {
+    await this.commands.eval(CLEAR_IF_OWNER, 1, deviceRouteKey(deviceId), replicaId);
+  }
+  async publish(channel, payload) {
+    await this.commands.publish(channel, payload);
+  }
+  /** 就绪探测(/readyz):命令连接 PING 一次。断连时 ioredis 会抛/挂起,由调用方限时。 */
+  async ping() {
+    await this.commands.ping();
+  }
+  async subscribe(channel, handler) {
+    this.handlers.set(channel, handler);
+    await this.subscriber.subscribe(channel);
+  }
+  async close() {
+    this.handlers.clear();
+    await Promise.allSettled([this.subscriber.quit(), this.commands.quit()]);
+  }
+};
+
 // src/sqliteSearchIndex.ts
 import Database from "better-sqlite3";
 var SCHEMA_SQL = TOOL_SEARCH_SCHEMA_STATEMENTS.map((sql) => `${sql};`).join("\n");
@@ -38246,13 +38752,18 @@ var SqliteSearchIndex = class extends SqlSearchIndex {
 
 // src/sqliteStateStore.ts
 import Database2 from "better-sqlite3";
-var DEFAULT_LIST_LIMIT = 1e3;
-function prefixUpperBound(prefix) {
-  for (let i = prefix.length - 1; i >= 0; i--) {
-    const code = prefix.charCodeAt(i);
-    if (code < 65535) {
-      return prefix.slice(0, i) + String.fromCharCode(code + 1);
-    }
+var DEFAULT_LIST_LIMIT2 = 1e3;
+var MAX_CODE_POINT2 = 1114111;
+var SURROGATE_START2 = 55296;
+var SURROGATE_END2 = 57343;
+function prefixUpperBound2(prefix) {
+  const points = [...prefix];
+  for (let i = points.length - 1; i >= 0; i--) {
+    const code = points[i]?.codePointAt(0);
+    if (code === void 0 || code >= MAX_CODE_POINT2) continue;
+    let next = code + 1;
+    if (next >= SURROGATE_START2 && next <= SURROGATE_END2) next = SURROGATE_END2 + 1;
+    return points.slice(0, i).join("") + String.fromCodePoint(next);
   }
   return void 0;
 }
@@ -38295,13 +38806,17 @@ var SqliteStateStore = class {
   async put(key, value) {
     this.stmtPut.run(key, JSON.stringify(value));
   }
+  async putIfAbsent(key, value) {
+    const info = this.db.prepare("INSERT OR IGNORE INTO kv (key, value) VALUES (?, ?)").run(key, JSON.stringify(value));
+    return info.changes > 0;
+  }
   async delete(key) {
     this.stmtDelete.run(key);
   }
   async list(prefix, opts) {
-    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT;
+    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT2;
     const lowerByCursor = opts?.cursor !== void 0 && opts.cursor >= prefix;
-    const upper = prefix === "" ? void 0 : prefixUpperBound(prefix);
+    const upper = prefix === "" ? void 0 : prefixUpperBound2(prefix);
     const conditions = [];
     const params = { n: limit + 1 };
     if (lowerByCursor) {
@@ -38330,14 +38845,16 @@ var SqliteStateStore = class {
 
 // src/server.ts
 import { serve } from "@hono/node-server";
+import postgres from "postgres";
 import { mkdirSync as mkdirSync2 } from "fs";
+import { hostname } from "os";
 import { join as join4 } from "path";
 
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.5.0",
-  description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
+  version: "0.10.0",
+  description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite or PostgreSQL persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
   type: "module",
   license: "MIT",
   main: "src/index.ts",
@@ -38385,6 +38902,8 @@ var package_default = {
     aws4fetch: "catalog:",
     "better-sqlite3": "^12.6.0",
     hono: "catalog:",
+    ioredis: "^6.0.0",
+    postgres: "^3.4.9",
     ws: "catalog:"
   },
   devDependencies: {
@@ -38449,24 +38968,116 @@ function resolveUiAssets(uiDirOverride) {
 }
 
 // src/server.ts
-function createTbServer(config) {
-  mkdirSync2(config.dataDir, { recursive: true });
-  const dbPath = join4(config.dataDir, "state.sqlite3");
-  const state = new SqliteStateStore(dbPath);
-  let search;
+function pgBackends(databaseUrl) {
+  const sql = postgres(databaseUrl, { onnotice: () => {
+  } });
+  const state = new PgStateStore(sql);
+  const search = new PgSearchIndex(sql);
+  return {
+    state: {
+      value: state,
+      ensureReady: async () => await state.ensureSchema(),
+      ping: async () => {
+        await sql`SELECT 1`;
+      },
+      close: async () => await sql.end({ timeout: 5 })
+    },
+    search: {
+      value: search,
+      ensureReady: async () => {
+        await search.initialized();
+      },
+      close: async () => {
+      }
+    }
+  };
+}
+function sqliteStateBackend(dataDir) {
+  const store = new SqliteStateStore(join4(dataDir, "state.sqlite3"));
+  return {
+    value: store,
+    ensureReady: async () => {
+    },
+    close: async () => store.close()
+  };
+}
+function sqliteSearchBackend(dataDir) {
+  const index = new SqliteSearchIndex(join4(dataDir, "state.sqlite3"));
+  return {
+    value: index,
+    ensureReady: async () => {
+    },
+    close: async () => index.close()
+  };
+}
+function resolveBackends(config) {
+  if (config.databaseUrl !== void 0) return pgBackends(config.databaseUrl);
+  const state = sqliteStateBackend(config.dataDir);
   try {
-    search = new SqliteSearchIndex(dbPath);
+    return { search: sqliteSearchBackend(config.dataDir), state };
   } catch (error) {
-    state.close();
+    state.close().catch(() => {
+    });
     throw error;
   }
+}
+function createTbServer(config) {
+  mkdirSync2(config.dataDir, { recursive: true });
+  const backends = resolveBackends(config);
+  const state = backends.state.value;
+  const search = backends.search.value;
   const secrets = new SecretStoreImpl(state, config.encryptionKey);
-  const objects = createDataObjectStore(config.dataDir);
+  const objects = config.objectStore === void 0 ? createDataObjectStore(config.dataDir) : createS3ObjectStore(config.objectStore, { allowInsecure: config.allowInsecureHttp });
+  const redisBackend = config.redisUrl === void 0 ? void 0 : new RedisDeviceRouterBackend(config.redisUrl);
   const hub = new DeviceHub({
     store: state,
     search,
-    reclaimSec: config.deviceReclaimSec
-  });
+    reclaimSec: config.deviceReclaimSec,
+    // 配了 Redis 才启用多副本路由;缺省单副本,设备调用恒走本地 socket。
+    ...redisBackend === void 0 ? {} : {
+      router: (onLocalCall) => new DeviceRouter(
+        config.replicaId ?? hostname(),
+        redisBackend,
+        { onLocalCall }
+      )
+    }
+  });
+  let draining = false;
+  const probeOne = async (fn) => {
+    let timer;
+    try {
+      await Promise.race([
+        fn(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error("timeout after 1000ms")), 1e3);
+          timer.unref?.();
+        })
+      ]);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : "probe failed" };
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  };
+  const readiness = async () => {
+    const checks = {};
+    const probes = [];
+    const statePing = backends.state.ping;
+    if (statePing !== void 0) {
+      probes.push(probeOne(statePing).then((r) => {
+        checks.state = r;
+      }));
+    }
+    if (redisBackend !== void 0) {
+      probes.push(probeOne(async () => await redisBackend.ping()).then((r) => {
+        checks.redis = r;
+      }));
+    }
+    await Promise.all(probes);
+    if (draining) checks.draining = { ok: false, detail: "shutting down" };
+    return { checks, ready: !draining && Object.values(checks).every((c) => c.ok) };
+  };
   const deps = {
     state,
     secrets,
@@ -38475,7 +39086,8 @@ function createTbServer(config) {
     search,
     allowInsecureHttp: config.allowInsecureHttp,
     objects: () => objects,
-    device: hub
+    device: hub,
+    readiness
   };
   if (config.encryptionKey !== void 0) deps.encryptionKey = config.encryptionKey;
   if (config.pluginBindings !== void 0) deps.pluginBindings = config.pluginBindings;
@@ -38494,6 +39106,9 @@ function createTbServer(config) {
     state,
     deviceHub: hub,
     async start() {
+      await backends.state.ensureReady();
+      await backends.search.ensureReady();
+      await hub.startRouter();
       await runBootstrap(state, {
         ...config.adminSk !== void 0 ? { adminSk: config.adminSk } : {},
         requireAdminSk: !config.allowInsecureBootstrap
@@ -38506,16 +39121,24 @@ function createTbServer(config) {
         hub.attach(server);
       });
     },
+    startDraining() {
+      draining = true;
+    },
     async close() {
-      await hub.close();
+      draining = true;
+      let closed;
       if (server !== void 0) {
-        await new Promise((resolve3, reject) => {
-          server?.close((err) => err ? reject(err) : resolve3());
+        const s = server;
+        closed = new Promise((resolve3, reject) => {
+          s.close((err) => err ? reject(err) : resolve3());
         });
-        server = void 0;
+        s.closeIdleConnections?.();
       }
-      search.close();
-      state.close();
+      await hub.close();
+      if (closed !== void 0) await closed;
+      server = void 0;
+      await backends.search.close();
+      await backends.state.close();
     }
   };
 }
@@ -38524,7 +39147,13 @@ export {
   configFromEnv,
   DEVICE_WS_PATH,
   DeviceHub,
+  DEVICE_ROUTE_TTL_SEC,
+  DEVICE_FORWARD_TIMEOUT_MS,
+  DeviceRouter,
   createDataObjectStore,
+  PgSearchIndex,
+  PgStateStore,
+  RedisDeviceRouterBackend,
   SqliteSearchIndex,
   SqliteStateStore,
   createTbServer