@tool-bridge/server 0.19.0 → 0.21.0

package/dist/{chunk-CLEZ6YQ6.js → chunk-MDY7K5CX.js}

@@ -1,6 +1,6 @@
 import {
   createGuardedFetch
-} from "./chunk-SWBNHIO4.js";
+} from "./chunk-ZTTN6AJG.js";
 import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
@@ -9,6 +9,7 @@ import {
   DEFAULT_STORE_DRIVER_KEY_ROOT,
   DEVICE_CALL_TIMEOUT_MS,
   DeviceGatewaySession,
+  DeviceMailboxService,
   FEEDBACK_HIDE_SCORE,
   FeedbackStore,
   HEADER_TB_CONTEXT,
@@ -54,6 +55,7 @@ import {
   any,
   appendVia,
   array,
+  assertNoCollision,
   assertPluginPayloadSize,
   assertPresignTtlSec,
   assertSecretRefUse,
@@ -90,6 +92,16 @@ import {
   derivePresence,
   deviceDirectoryHelpModel,
   deviceFsHelpModel,
+  deviceOperationClaimRequestSchema,
+  deviceOperationClaimResponseSchema,
+  deviceOperationCompleteRequestSchema,
+  deviceOperationDetailSchema,
+  deviceOperationIdentityRequestSchema,
+  deviceOperationListRequestSchema,
+  deviceOperationListResponseSchema,
+  deviceOperationRenewRequestSchema,
+  deviceOperationRenewResponseSchema,
+  deviceOperationSummarySchema,
   deviceShellHelpModel,
   discriminatedUnion,
   dispatchContextCmd,
@@ -185,7 +197,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-OKRZPQ3R.js";
+} from "./chunk-MZCIPUNQ.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -810,300 +822,48 @@ function createS3ObjectStore(cfg, opts) {
   };
 }
 
-// ../app/src/providers/toolCache.ts
-var KEY_PREFIX = "toolcache:";
-function toolCacheKey(path) {
-  return `${KEY_PREFIX}${path}`;
-}
-function isCached(v) {
-  return typeof v === "object" && v !== null && Array.isArray(v.tools) && typeof v.fetchedAt === "string";
-}
-function isFresh(fetchedAt, ttl, now) {
-  const age = (Date.parse(now) - Date.parse(fetchedAt)) / 1e3;
-  return Number.isFinite(age) && age >= 0 && age < ttl;
-}
-async function invalidateToolCache(store, path) {
-  await store.delete(toolCacheKey(path));
-}
-function cachedTools(value) {
-  return isCached(value) ? value.tools : null;
-}
-async function peekToolCache(store, path) {
-  return cachedTools(await store.get(toolCacheKey(path)));
-}
-async function getTools(store, path, fetchList, opts) {
-  if (!opts.refresh) {
-    const raw = await store.get(toolCacheKey(path));
-    if (isCached(raw) && isFresh(raw.fetchedAt, opts.ttl, opts.now)) {
-      return raw.tools;
-    }
-  }
-  await opts.beforeFresh?.();
-  try {
-    const tools = await fetchList();
-    const record2 = { tools, fetchedAt: opts.now };
-    await store.put(toolCacheKey(path), record2);
-    await opts.onFresh?.(tools);
-    return tools;
-  } catch (error) {
-    await opts.onFreshError?.();
-    throw error;
-  }
-}
+// ../app/src/deps.ts
+var TOOL_CACHE_TTL_DEFAULT = 300;
 
-// ../app/src/search/synchronizer.ts
-var DIRTY_NODE_PREFIX = "searchdirty:node:";
-var DIRTY_SUBTREE_PREFIX = "searchdirty:subtree:";
-function isMutableSearchIndex(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const index = value;
-  return typeof index.replace === "function" && typeof index.remove === "function" && typeof index.removePrefix === "function" && typeof index.rebuild === "function" && typeof index.initialized === "function";
-}
-function toolNode(node) {
-  return (node.kind === "mcp" || node.kind === "http" || node.kind === "tool") && node.config?.kind === node.kind;
-}
-function httpTools(node) {
-  if (node.config?.kind !== "http") return null;
-  return node.config.tools.map((tool) => {
-    const spec = {
-      description: tool.description,
-      effect: effectFor(tool),
-      name: tool.name
-    };
-    if (tool.inputSchema !== void 0) spec.inputSchema = tool.inputSchema;
-    return spec;
-  });
-}
-function deviceTools(node) {
-  if (node.config?.kind !== "tool") return null;
-  const cmds = node.config.providerConfig?.cmds;
-  if (!Array.isArray(cmds)) return null;
-  return cmds;
-}
-async function canonicalSearchTools(state, nodes) {
-  const unique = new Map(nodes.map((node) => [node.path, node]));
-  const dynamicPaths = [...unique.values()].filter((node) => node.kind !== "http" && deviceTools(node) === null).map((node) => node.path);
-  const cached = dynamicPaths.length === 0 ? /* @__PURE__ */ new Map() : await state.getMany(dynamicPaths.map(toolCacheKey));
-  const result = /* @__PURE__ */ new Map();
-  for (const node of unique.values()) {
-    const tools = node.kind === "http" ? httpTools(node) : deviceTools(node) ?? cachedTools(cached.get(toolCacheKey(node.path)));
-    if (tools !== null) result.set(node.path, tools);
+// ../app/src/cursorCleanup.ts
+function positiveInt(value, fallback, field) {
+  const actual = value ?? fallback;
+  if (!Number.isSafeInteger(actual) || actual < 1) {
+    throw new TBError("invalid_argument", `${field} must be a positive integer`);
   }
-  return result;
-}
-function documentsFor(path, tools, feedback) {
-  return tools.map((tool) => ({ path, tool, ...feedback === "" ? {} : { feedback } }));
+  return actual;
 }
-var SearchSynchronizer = class {
-  constructor(state, search) {
-    this.state = state;
-    this.search = search;
-    this.registry = new NodeRegistryStore(state);
-  }
-  state;
-  search;
-  registry;
-  seedPromise;
-  async mark(path, kind) {
-    const canonical = normalizeToolSearchPath(path);
-    const marker = {
-      createdAt: Date.now(),
-      // Marker 只是审计提示，正确性由每次 canonical audit 保证。每类固定一个 key，
-      // 避免 overflow/device hello 用 UUID marker 把 KV 与扫描成本无界放大。
-      key: `${kind === "node" ? DIRTY_NODE_PREFIX : DIRTY_SUBTREE_PREFIX}pending`,
-      kind,
-      path: canonical
-    };
-    await this.state.put(marker.key, marker);
-    return marker;
-  }
-  async markNode(path) {
-    return await this.mark(path, "node");
-  }
-  async markSubtree(path) {
-    return await this.mark(path, "subtree");
-  }
-  async abort(marker) {
-    if (marker !== void 0 && marker.expectedDigest === void 0) {
-      await this.state.delete(marker.key);
-    }
-  }
-  async dirtyMarkers() {
-    const markers = [];
-    for (const prefix of [DIRTY_NODE_PREFIX, DIRTY_SUBTREE_PREFIX]) {
-      let cursor;
-      do {
-        const page = await this.state.list(prefix, {
-          limit: 200,
-          ...cursor === void 0 ? {} : { cursor }
-        });
-        for (const item of page.items) {
-          const marker = item.value;
-          if (typeof marker.createdAt === "number" && marker.key === item.key && (marker.kind === "node" || marker.kind === "subtree") && typeof marker.path === "string") {
-            markers.push(marker);
-          }
-        }
-        cursor = page.cursor;
-      } while (cursor !== void 0);
-    }
-    return markers;
-  }
-  async commitMarker(marker, expectedDigest) {
-    if (marker === void 0) return;
-    const committed = {
-      ...marker,
-      committedAt: Date.now(),
-      expectedDigest
-    };
-    await this.state.put(marker.key, committed);
-    Object.assign(marker, committed);
-  }
-  async finishMarker(marker) {
-    if (marker !== void 0) await this.state.delete(marker.key);
-  }
-  async feedbackText(path, snapshot) {
-    if (snapshot !== void 0) return selectFeedbackSearchText(snapshot);
-    return selectFeedbackSearchText(parseFeedbackEntries(await this.state.get(KEY_FEEDBACK + path)));
-  }
-  async rawTools(node, override) {
-    if (override !== void 0) return [...override];
-    if (node.kind === "http") return httpTools(node);
-    const device = deviceTools(node);
-    if (device !== null) return device;
-    if (node.kind === "mcp" || node.kind === "tool") {
-      return await peekToolCache(this.state, node.path);
-    }
-    return null;
-  }
-  indexableRecords(path, tools, feedback) {
-    try {
-      return serializeToolSearchSnapshot(path, tools, feedback);
-    } catch (error) {
-      if (isTBError(error)) return null;
-      throw error;
-    }
-  }
-  async reconcileNode(path, opts = {}) {
-    const canonical = normalizeToolSearchPath(path);
-    const node = await this.registry.get(canonical).catch(() => null);
-    if (node === null || !toolNode(node)) {
-      await this.commitMarker(opts.marker, null);
-      await this.search.remove(canonical);
-      await this.finishMarker(opts.marker);
-      return;
-    }
-    const tools = await this.rawTools(node, opts.tools);
-    if (tools === null) {
-      await this.search.remove(canonical);
-      await this.finishMarker(opts.marker);
-      return;
-    }
-    if (tools.length === 0) {
-      await this.commitMarker(opts.marker, null);
-      await this.search.remove(canonical);
-      await this.finishMarker(opts.marker);
-      return;
-    }
-    const root = await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
-    if (root.truncated) {
-      await this.finishMarker(opts.marker);
-      return;
-    }
-    const feedback = await this.feedbackText(canonical, opts.feedback);
-    const records = this.indexableRecords(canonical, tools, feedback);
-    if (records === null) {
-      await this.commitMarker(opts.marker, null);
-      await this.search.remove(canonical);
-      await this.finishMarker(opts.marker);
-      return;
-    }
-    const digest = records.length === 0 ? null : toolSearchSnapshotDigest(records);
-    await this.commitMarker(opts.marker, digest);
-    await this.search.replace(canonical, tools, {
-      feedback
-    });
-    await this.finishMarker(opts.marker);
-  }
-  /** mutation 热路径使用：canonical 已成功时，派生同步失败只保留 marker。 */
-  async reconcileNodeQuietly(path, opts = {}) {
-    try {
-      await this.reconcileNode(path, opts);
-    } catch {
-    }
-  }
-  async rebuildAll(markers = [], opts = {}) {
-    const snapshot = opts.canonicalNodes === void 0 ? await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT) : { items: [...opts.canonicalNodes], truncated: false };
-    if (snapshot.truncated) return false;
-    const nodes = snapshot.items.filter(toolNode);
-    const authoritativeEmpty = new Set(opts.authoritativeEmpty ?? []);
-    const keys = nodes.flatMap((node) => [KEY_FEEDBACK + node.path, toolCacheKey(node.path)]);
-    const values = await this.state.getMany(keys);
-    const documents = [];
-    for (const node of nodes) {
-      if (authoritativeEmpty.has(node.path)) continue;
-      let tools;
-      if (node.kind === "http") {
-        tools = httpTools(node);
-      } else {
-        tools = deviceTools(node) ?? cachedTools(values.get(toolCacheKey(node.path)));
-      }
-      if (tools === null) continue;
-      const feedback = selectFeedbackSearchText(
-        parseFeedbackEntries(values.get(KEY_FEEDBACK + node.path))
-      );
-      if (this.indexableRecords(node.path, tools, feedback) === null) continue;
-      documents.push(...documentsFor(node.path, tools, feedback));
-    }
-    await this.search.rebuild(documents);
-    await Promise.all(markers.map(async (marker) => {
-      await this.state.delete(marker.key).catch(() => {
-      });
-    }));
-    return true;
-  }
-  /** 每次搜索前审计 canonical 快照；同快照 rebuild 不 bump revision。 */
-  async ensureReady() {
-    const snapshot = await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
-    if (snapshot.truncated) {
-      if (await this.search.initialized()) return;
-      throw new TBError("rate_limited", "registry \u8D85\u51FA\u5DE5\u5177\u641C\u7D22 canonical audit \u5BB9\u91CF");
-    }
-    const dirty = await this.dirtyMarkers();
-    await this.rebuildAll(dirty, { canonicalNodes: snapshot.items });
-  }
-  /** 首次 registry/device mutation 前建立 last-known-good，避免并发溢出抢在首次 seed 前。 */
-  async ensureSeeded() {
-    if (await this.search.initialized()) return;
-    if (this.seedPromise === void 0) {
-      this.seedPromise = (async () => {
-        if (!await this.rebuildAll()) {
-          throw new TBError("rate_limited", "registry \u8D85\u51FA\u5DE5\u5177\u641C\u7D22 canonical audit \u5BB9\u91CF");
-        }
-      })();
-    }
-    try {
-      await this.seedPromise;
-    } finally {
-      this.seedPromise = void 0;
-    }
-  }
-  async removeSubtreeQuietly(path, marker) {
-    try {
-      const canonical = normalizeToolSearchPath(path);
-      if ((await this.registry.subtree(canonical)).length === 0) {
-        await this.commitMarker(marker, null);
-        await this.search.removePrefix(canonical);
-        await this.finishMarker(marker);
-      } else {
-        await this.rebuildAll(marker === void 0 ? [] : [marker]);
+async function runCursorCleanup(opts) {
+  const { state } = opts;
+  if (state.compareAndSwap === void 0) {
+    throw new TBError("unavailable", "cursor cleanup requires StateStore.compareAndSwap");
+  }
+  const raw = await state.get(opts.progressKey);
+  let progress = raw === null ? null : opts.parseProgress(raw);
+  let cursor = progress?.cursor;
+  for (let pageNumber = 0; pageNumber < opts.maxPages; pageNumber++) {
+    const nextCursor = await opts.runPage(cursor, pageNumber);
+    if (nextCursor === void 0) {
+      if (progress !== null) {
+        await state.compareAndSwap(opts.progressKey, progress.revision, null);
       }
-    } catch {
+      return void 0;
     }
+    const next = {
+      cursor: nextCursor,
+      revision: (progress?.revision ?? 0) + 1
+    };
+    const advanced = await state.compareAndSwap(
+      opts.progressKey,
+      progress?.revision ?? null,
+      opts.encodeProgress(next)
+    );
+    if (!advanced) return void 0;
+    progress = next;
+    cursor = next.cursor;
   }
-};
-
-// ../app/src/deps.ts
-var TOOL_CACHE_TTL_DEFAULT = 300;
+  return cursor;
+}
 
 // ../app/src/storeRefToken.ts
 async function hmacKey(secret) {
@@ -1162,13 +922,6 @@ var STORE_READ_TTL_SEC_DEFAULT = 15 * 60;
 var STORE_CALL_MAX_OBJECTS_DEFAULT = 4;
 var STORE_CALL_MAX_OBJECT_BYTES_DEFAULT = 256 * 1024 * 1024;
 var STORE_CALL_MAX_BYTES_DEFAULT = 512 * 1024 * 1024;
-function positiveInt(value, fallback, field) {
-  const actual = value ?? fallback;
-  if (!Number.isSafeInteger(actual) || actual < 1) {
-    throw new TBError("invalid_argument", `${field} must be a positive integer`);
-  }
-  return actual;
-}
 function randomSecret() {
   const bytes = crypto.getRandomValues(new Uint8Array(32));
   let out = "";
@@ -1501,44 +1254,28 @@ async function cleanupDefaultStore(deps, opts = {}) {
   const store = await defaultStoreRuntime(deps);
   const maxPages = Math.min(positiveInt(opts.maxPages, 8, "maxPages"), 64);
   const limit = opts.limit === void 0 ? void 0 : positiveInt(opts.limit, 200, "limit");
-  const rawProgress = await deps.state.get(KEY_STORE_CLEANUP_PROGRESS);
-  let progress = rawProgress === null ? null : cleanupProgress(rawProgress);
-  let cursors = progress?.cursors;
   const aggregate = emptyCleanupResult();
-  for (let pageNumber = 0; pageNumber < maxPages; pageNumber++) {
-    const page = await store.service.cleanup({
-      ...limit === void 0 ? {} : { limit },
-      ...cursors === void 0 ? {} : { cursors },
-      // staging 不使用权威状态 cursor；同一 host tick 只运行一次，避免
-      // maxPages 内重复扫描同一 driver maintenance 范围。
-      runDriverMaintenance: pageNumber === 0
-    });
-    addCleanupResult(aggregate, page);
-    if (page.cursors === void 0) {
-      if (progress !== null) {
-        await deps.state.compareAndSwap(
-          KEY_STORE_CLEANUP_PROGRESS,
-          progress.revision,
-          null
-        );
-      }
-      return aggregate;
-    }
-    const next = {
-      cursors: page.cursors,
-      revision: (progress?.revision ?? 0) + 1
-    };
-    const advanced = await deps.state.compareAndSwap(
-      KEY_STORE_CLEANUP_PROGRESS,
-      progress?.revision ?? null,
-      next
-    );
-    if (!advanced) {
-      return aggregate;
-    }
-    progress = next;
-    cursors = next.cursors;
-  }
+  const cursors = await runCursorCleanup({
+    encodeProgress: (progress) => ({ cursors: progress.cursor, revision: progress.revision }),
+    maxPages,
+    parseProgress: (value) => {
+      const progress = cleanupProgress(value);
+      return { cursor: progress.cursors, revision: progress.revision };
+    },
+    progressKey: KEY_STORE_CLEANUP_PROGRESS,
+    runPage: async (cursor, pageNumber) => {
+      const page = await store.service.cleanup({
+        ...limit === void 0 ? {} : { limit },
+        ...cursor === void 0 ? {} : { cursors: cursor },
+        // staging 不使用权威状态 cursor；同一 host tick 只运行一次，避免
+        // maxPages 内重复扫描同一 driver maintenance 范围。
+        runDriverMaintenance: pageNumber === 0
+      });
+      addCleanupResult(aggregate, page);
+      return page.cursors;
+    },
+    state: deps.state
+  });
   return { ...aggregate, ...cursors === void 0 ? {} : { cursors } };
 }
 
@@ -1552,12 +1289,12 @@ function requireDevice(deps) {
   }
   return deps.device;
 }
-async function invokeDevice(deps, deviceId, req) {
+async function attemptDevice(deps, deviceId, req) {
   const id = crypto.randomUUID();
   const upload = req.context === void 0 ? null : await issueDeviceCallUpload(deps, deviceId, id, req.context);
-  let body;
+  let attempt2;
   try {
-    body = await requireDevice(deps).invoke(deviceId, {
+    attempt2 = await requireDevice(deps).invoke(deviceId, {
       id,
       path: req.path,
       arguments: req.arguments,
@@ -1567,11 +1304,15 @@ async function invokeDevice(deps, deviceId, req) {
     await upload?.revoke().catch(() => {
     });
   }
-  if (!body || !("ok" in body)) {
+  if (attempt2 === null || typeof attempt2 !== "object" || !["completed", "not_dispatched", "unknown"].includes(attempt2.disposition) || attempt2.result === null || typeof attempt2.result !== "object" || !("ok" in attempt2.result) || attempt2.disposition !== "completed" && attempt2.result.ok !== false) {
     throw new TBError("unavailable", "device session returned invalid result");
   }
-  if (body.ok) return body.value;
-  throw tbErrorFromBody(body.error);
+  return attempt2;
+}
+async function invokeDevice(deps, deviceId, req) {
+  const attempt2 = await attemptDevice(deps, deviceId, req);
+  if (attempt2.result.ok) return attempt2.result.value;
+  throw tbErrorFromBody(attempt2.result.error);
 }
 function deviceCallContextFrom(ctx) {
   const now = Date.now();
@@ -19794,8 +19535,6 @@ function createPluginToolProvider(opts) {
 
 // ../app/src/providerOAuth.ts
 var KEY_TOKENS = "puoauth:token:";
-var STATE_TTL_SEC2 = 600;
-var PROVIDER_OAUTH_CALLBACK_PATH = "/~oauth/callback";
 async function invalidateProviderOAuth(store, nodePath) {
   await store.delete(KEY_TOKENS + nodePath);
 }
@@ -19870,15 +19609,10 @@ async function requestTokens(opts) {
     throw err;
   }
 }
-function base64url(bytes) {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
-}
 async function createPkce() {
-  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  const verifier = base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
-  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+  return { verifier, challenge: base64urlEncode(new Uint8Array(digest)) };
 }
 function requireProviderOAuthFetch(fetcher) {
   if (fetcher === void 0) {
@@ -19914,7 +19648,7 @@ async function startProviderAuthorization(opts) {
     {
       p: opts.nodePath,
       v: pkce?.verifier ?? "",
-      exp: Math.floor(opts.now.getTime() / 1e3) + STATE_TTL_SEC2
+      exp: Math.floor(opts.now.getTime() / 1e3) + STATE_TTL_SEC
     },
     opts.encryptionKey
   );
@@ -19923,7 +19657,7 @@ async function startProviderAuthorization(opts) {
     authorizationUrl: buildAuthorizationUrl({
       config: opts.config,
       clientId: client.clientId,
-      redirectUri: opts.origin + PROVIDER_OAUTH_CALLBACK_PATH,
+      redirectUri: opts.origin + OAUTH_CALLBACK_PATH,
       state,
       ...pkce === void 0 ? {} : { codeChallenge: pkce.challenge }
     })
@@ -19936,7 +19670,7 @@ async function finishProviderAuthorization(opts) {
     config: opts.config,
     fetcher,
     now: opts.now,
-    grant: { code: opts.code, redirectUri: opts.origin + PROVIDER_OAUTH_CALLBACK_PATH },
+    grant: { code: opts.code, redirectUri: opts.origin + OAUTH_CALLBACK_PATH },
     ...opts.codeVerifier === "" ? {} : { codeVerifier: opts.codeVerifier },
     ...client
   });
@@ -19966,21 +19700,61 @@ async function resolveProviderAccessToken(opts) {
   return refreshed.accessToken;
 }
 
+// ../app/src/providers/toolCache.ts
+var KEY_PREFIX = "toolcache:";
+function toolCacheKey(path) {
+  return `${KEY_PREFIX}${path}`;
+}
+function isCached(v) {
+  return typeof v === "object" && v !== null && Array.isArray(v.tools) && typeof v.fetchedAt === "string";
+}
+function isFresh(fetchedAt, ttl, now) {
+  const age = (Date.parse(now) - Date.parse(fetchedAt)) / 1e3;
+  return Number.isFinite(age) && age >= 0 && age < ttl;
+}
+async function invalidateToolCache(store, path) {
+  await store.delete(toolCacheKey(path));
+}
+function cachedTools(value) {
+  return isCached(value) ? value.tools : null;
+}
+async function peekToolCache(store, path) {
+  return cachedTools(await store.get(toolCacheKey(path)));
+}
+async function getTools(store, path, fetchList, opts) {
+  if (!opts.refresh) {
+    const raw = await store.get(toolCacheKey(path));
+    if (isCached(raw) && isFresh(raw.fetchedAt, opts.ttl, opts.now)) {
+      return raw.tools;
+    }
+  }
+  await opts.beforeFresh?.();
+  try {
+    const tools = await fetchList();
+    const record2 = { tools, fetchedAt: opts.now };
+    await store.put(toolCacheKey(path), record2);
+    await opts.onFresh?.(tools);
+    return tools;
+  } catch (error) {
+    await opts.onFreshError?.();
+    throw error;
+  }
+}
+
 // ../app/src/toolNodes.ts
-function upstreamTools(node, provider, deps, refresh, now) {
+function upstreamTools(node, provider, deps, refresh, now, searchSync) {
   if (node.kind === "mcp" || node.kind === "tool") {
-    const sync = isMutableSearchIndex(deps.search) ? new SearchSynchronizer(deps.state, deps.search) : void 0;
     let marker;
     return getTools(deps.state, node.path, () => provider.list(), {
       refresh,
       ttl: deps.toolCacheTtlSec ?? TOOL_CACHE_TTL_DEFAULT,
       now,
-      ...sync === void 0 ? {} : {
+      ...searchSync === void 0 ? {} : {
         beforeFresh: async () => {
-          marker = await sync.markNode(node.path);
+          marker = await searchSync.markNode(node.path);
         },
-        onFreshError: async () => await sync.abort(marker),
-        onFresh: async (tools) => await sync.reconcileNodeQuietly(node.path, { marker, tools })
+        onFreshError: async () => await searchSync.abort(marker),
+        onFresh: async (tools) => await searchSync.reconcileNodeQuietly(node.path, { marker, tools })
       }
     });
   }
@@ -20115,11 +19889,11 @@ async function providerFor(node, ctx, deps) {
   }
   throw TBError.unimplemented(`kind '${node.kind}' has no tool provider`);
 }
-async function refreshDynamicSearchNode(node, ctx, deps) {
+async function refreshDynamicSearchNode(node, ctx, deps, searchSync) {
   if (node.kind !== "mcp" && node.kind !== "tool" || deviceToolMarker(node) !== null) return false;
   try {
     const provider = await providerFor(node, ctx, deps);
-    await upstreamTools(node, provider, deps, true, (/* @__PURE__ */ new Date()).toISOString());
+    await upstreamTools(node, provider, deps, true, (/* @__PURE__ */ new Date()).toISOString(), searchSync);
     return true;
   } catch {
     return false;
@@ -20134,7 +19908,7 @@ async function refreshDynamicToolCache(node, ctx, deps) {
     now: (/* @__PURE__ */ new Date()).toISOString()
   });
 }
-async function toolHelpModelFor(c, ctx, registry, path, deps) {
+async function toolHelpModelFor(c, ctx, registry, path, deps, searchSync) {
   let resolved;
   try {
     resolved = await registry.resolve(path);
@@ -20155,7 +19929,7 @@ async function toolHelpModelFor(c, ctx, registry, path, deps) {
   }
   const provider = await providerFor(node, ctx, deps);
   const refresh = c.req.query("refresh") === "1";
-  const raw = await upstreamTools(node, provider, deps, refresh, (/* @__PURE__ */ new Date()).toISOString());
+  const raw = await upstreamTools(node, provider, deps, refresh, (/* @__PURE__ */ new Date()).toISOString(), searchSync);
   const { exposed } = virtualizeTools(node.virtualize, raw);
   const tool = exposed.find((t) => t.name === rest);
   if (tool === void 0) return null;
@@ -20308,9 +20082,6 @@ async function verifyRefToken(token, secret) {
 function localContext(deps, node) {
   return deps.locals?.context?.(node.path) ?? null;
 }
-function localCapabilities(provider) {
-  return contextCapabilitiesOf(provider);
-}
 function parseS3Credentials(raw, refName) {
   try {
     const v = JSON.parse(raw);
@@ -20387,13 +20158,8 @@ async function createContextUploadGrant(node, cfg, deps, input) {
     uploadGrantTtlSec
   }, input);
 }
-async function contextProviderFor(node, cfg, deps, requestUrl) {
-  const objects = await contextObjectStoreFor(cfg, deps);
-  const opts = {
-    nsPath: node.path,
-    keyPrefix: contextKeyPrefix(cfg, node.path),
-    readOnly: cfg.readOnly ?? false
-  };
+function objectProviderOpts(node, keyPrefix, readOnly, deps, requestUrl) {
+  const opts = { nsPath: node.path, keyPrefix, readOnly };
   if (deps.refThresholdBytes !== void 0) opts.refThresholdBytes = deps.refThresholdBytes;
   if (deps.refTtlSec !== void 0) opts.presignTtlSec = deps.refTtlSec;
   const encKey = deps.encryptionKey;
@@ -20405,7 +20171,17 @@ async function contextProviderFor(node, cfg, deps, requestUrl) {
       return `${origin}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
     };
   }
-  return createObjectContextProvider(objects, opts);
+  return opts;
+}
+async function contextProviderFor(node, cfg, deps, requestUrl) {
+  const objects = await contextObjectStoreFor(cfg, deps);
+  return createObjectContextProvider(objects, objectProviderOpts(
+    node,
+    contextKeyPrefix(cfg, node.path),
+    cfg.readOnly ?? false,
+    deps,
+    requestUrl
+  ));
 }
 function skillhubKeyPrefix(cfg, nodePath) {
   const prefix = cfg.providerConfig?.prefix;
@@ -20414,29 +20190,13 @@ function skillhubKeyPrefix(cfg, nodePath) {
 }
 async function skillhubProviderFor(node, cfg, deps, requestUrl) {
   const objects = await contextObjectStoreFor(cfg, deps);
-  const opts = {
-    nsPath: node.path,
-    keyPrefix: skillhubKeyPrefix(cfg, node.path),
-    readOnly: cfg.readOnly ?? false
-  };
-  if (deps.refThresholdBytes !== void 0) opts.refThresholdBytes = deps.refThresholdBytes;
-  if (deps.refTtlSec !== void 0) opts.presignTtlSec = deps.refTtlSec;
-  const encKey = deps.encryptionKey;
-  if (encKey !== void 0) {
-    const origin = new URL(requestUrl).origin;
-    const relayTtlSec = deps.refTtlSec ?? PRESIGN_TTL_SEC_DEFAULT;
-    opts.relayRefUrl = async (key) => {
-      const exp = Math.floor(Date.now() / 1e3) + relayTtlSec;
-      return `${origin}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
-    };
-  }
-  return createSkillhubProvider(objects, opts);
-}
-async function dispatchSkillhubCmd2(provider, command, args) {
-  return await dispatchSkillhubCmd(provider, command, args);
-}
-async function dispatchContextCmd2(provider, command, args) {
-  return await dispatchContextCmd(provider, command, args);
+  return createSkillhubProvider(objects, objectProviderOpts(
+    node,
+    skillhubKeyPrefix(cfg, node.path),
+    cfg.readOnly ?? false,
+    deps,
+    requestUrl
+  ));
 }
 async function assertContextAlive(node, cfg, registry) {
   if (!isContextExpired(node.createdAt, cfg.ttl, Date.now())) return;
@@ -20507,6 +20267,257 @@ async function assertSkillhubConfig(config, deps) {
   }
 }
 
+// ../app/src/search/synchronizer.ts
+var DIRTY_NODE_PREFIX = "searchdirty:node:";
+var DIRTY_SUBTREE_PREFIX = "searchdirty:subtree:";
+function isMutableSearchIndex(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const index = value;
+  return typeof index.replace === "function" && typeof index.remove === "function" && typeof index.removePrefix === "function" && typeof index.rebuild === "function" && typeof index.initialized === "function";
+}
+function toolNode(node) {
+  return (node.kind === "mcp" || node.kind === "http" || node.kind === "tool") && node.config?.kind === node.kind;
+}
+function httpTools(node) {
+  if (node.config?.kind !== "http") return null;
+  return node.config.tools.map((tool) => {
+    const spec = {
+      description: tool.description,
+      effect: effectFor(tool),
+      name: tool.name
+    };
+    if (tool.inputSchema !== void 0) spec.inputSchema = tool.inputSchema;
+    return spec;
+  });
+}
+function deviceTools(node) {
+  if (node.config?.kind !== "tool") return null;
+  const cmds = node.config.providerConfig?.cmds;
+  if (!Array.isArray(cmds)) return null;
+  return cmds;
+}
+async function canonicalSearchTools(state, nodes) {
+  const unique = new Map(nodes.map((node) => [node.path, node]));
+  const dynamicPaths = [...unique.values()].filter((node) => node.kind !== "http" && deviceTools(node) === null).map((node) => node.path);
+  const cached = dynamicPaths.length === 0 ? /* @__PURE__ */ new Map() : await state.getMany(dynamicPaths.map(toolCacheKey));
+  const result = /* @__PURE__ */ new Map();
+  for (const node of unique.values()) {
+    const tools = node.kind === "http" ? httpTools(node) : deviceTools(node) ?? cachedTools(cached.get(toolCacheKey(node.path)));
+    if (tools !== null) result.set(node.path, tools);
+  }
+  return result;
+}
+function documentsFor(path, tools, feedback) {
+  return tools.map((tool) => ({ path, tool, ...feedback === "" ? {} : { feedback } }));
+}
+var SearchSynchronizer = class {
+  constructor(state, search) {
+    this.state = state;
+    this.search = search;
+    this.registry = new NodeRegistryStore(state);
+  }
+  state;
+  search;
+  registry;
+  seedPromise;
+  async mark(path, kind) {
+    const canonical = normalizeToolSearchPath(path);
+    const marker = {
+      createdAt: Date.now(),
+      // Marker 只是审计提示，正确性由每次 canonical audit 保证。每类固定一个 key，
+      // 避免 overflow/device hello 用 UUID marker 把 KV 与扫描成本无界放大。
+      key: `${kind === "node" ? DIRTY_NODE_PREFIX : DIRTY_SUBTREE_PREFIX}pending`,
+      kind,
+      path: canonical
+    };
+    await this.state.put(marker.key, marker);
+    return marker;
+  }
+  async markNode(path) {
+    return await this.mark(path, "node");
+  }
+  async markSubtree(path) {
+    return await this.mark(path, "subtree");
+  }
+  async abort(marker) {
+    if (marker !== void 0 && marker.expectedDigest === void 0) {
+      await this.state.delete(marker.key);
+    }
+  }
+  async dirtyMarkers() {
+    const markers = [];
+    for (const prefix of [DIRTY_NODE_PREFIX, DIRTY_SUBTREE_PREFIX]) {
+      let cursor;
+      do {
+        const page = await this.state.list(prefix, {
+          limit: 200,
+          ...cursor === void 0 ? {} : { cursor }
+        });
+        for (const item of page.items) {
+          const marker = item.value;
+          if (typeof marker.createdAt === "number" && marker.key === item.key && (marker.kind === "node" || marker.kind === "subtree") && typeof marker.path === "string") {
+            markers.push(marker);
+          }
+        }
+        cursor = page.cursor;
+      } while (cursor !== void 0);
+    }
+    return markers;
+  }
+  async commitMarker(marker, expectedDigest) {
+    if (marker === void 0) return;
+    const committed = {
+      ...marker,
+      committedAt: Date.now(),
+      expectedDigest
+    };
+    await this.state.put(marker.key, committed);
+    Object.assign(marker, committed);
+  }
+  async finishMarker(marker) {
+    if (marker !== void 0) await this.state.delete(marker.key);
+  }
+  async feedbackText(path, snapshot) {
+    if (snapshot !== void 0) return selectFeedbackSearchText(snapshot);
+    return selectFeedbackSearchText(parseFeedbackEntries(await this.state.get(KEY_FEEDBACK + path)));
+  }
+  async rawTools(node, override) {
+    if (override !== void 0) return [...override];
+    if (node.kind === "http") return httpTools(node);
+    const device = deviceTools(node);
+    if (device !== null) return device;
+    if (node.kind === "mcp" || node.kind === "tool") {
+      return await peekToolCache(this.state, node.path);
+    }
+    return null;
+  }
+  indexableRecords(path, tools, feedback) {
+    try {
+      return serializeToolSearchSnapshot(path, tools, feedback);
+    } catch (error) {
+      if (isTBError(error)) return null;
+      throw error;
+    }
+  }
+  async reconcileNode(path, opts = {}) {
+    const canonical = normalizeToolSearchPath(path);
+    const node = await this.registry.get(canonical).catch(() => null);
+    if (node === null || !toolNode(node)) {
+      await this.commitMarker(opts.marker, null);
+      await this.search.remove(canonical);
+      await this.finishMarker(opts.marker);
+      return;
+    }
+    const tools = await this.rawTools(node, opts.tools);
+    if (tools === null) {
+      await this.search.remove(canonical);
+      await this.finishMarker(opts.marker);
+      return;
+    }
+    if (tools.length === 0) {
+      await this.commitMarker(opts.marker, null);
+      await this.search.remove(canonical);
+      await this.finishMarker(opts.marker);
+      return;
+    }
+    const root = await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
+    if (root.truncated) {
+      await this.finishMarker(opts.marker);
+      return;
+    }
+    const feedback = await this.feedbackText(canonical, opts.feedback);
+    const records = this.indexableRecords(canonical, tools, feedback);
+    if (records === null) {
+      await this.commitMarker(opts.marker, null);
+      await this.search.remove(canonical);
+      await this.finishMarker(opts.marker);
+      return;
+    }
+    const digest = records.length === 0 ? null : toolSearchSnapshotDigest(records);
+    await this.commitMarker(opts.marker, digest);
+    await this.search.replace(canonical, tools, {
+      feedback
+    });
+    await this.finishMarker(opts.marker);
+  }
+  /** mutation 热路径使用：canonical 已成功时，派生同步失败只保留 marker。 */
+  async reconcileNodeQuietly(path, opts = {}) {
+    try {
+      await this.reconcileNode(path, opts);
+    } catch {
+    }
+  }
+  async rebuildAll(markers = [], opts = {}) {
+    const snapshot = opts.canonicalNodes === void 0 ? await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT) : { items: [...opts.canonicalNodes], truncated: false };
+    if (snapshot.truncated) return false;
+    const nodes = snapshot.items.filter(toolNode);
+    const authoritativeEmpty = new Set(opts.authoritativeEmpty ?? []);
+    const keys = nodes.flatMap((node) => [KEY_FEEDBACK + node.path, toolCacheKey(node.path)]);
+    const values = await this.state.getMany(keys);
+    const documents = [];
+    for (const node of nodes) {
+      if (authoritativeEmpty.has(node.path)) continue;
+      let tools;
+      if (node.kind === "http") {
+        tools = httpTools(node);
+      } else {
+        tools = deviceTools(node) ?? cachedTools(values.get(toolCacheKey(node.path)));
+      }
+      if (tools === null) continue;
+      const feedback = selectFeedbackSearchText(
+        parseFeedbackEntries(values.get(KEY_FEEDBACK + node.path))
+      );
+      if (this.indexableRecords(node.path, tools, feedback) === null) continue;
+      documents.push(...documentsFor(node.path, tools, feedback));
+    }
+    await this.search.rebuild(documents);
+    await Promise.all(markers.map(async (marker) => {
+      await this.state.delete(marker.key).catch(() => {
+      });
+    }));
+    return true;
+  }
+  /** 每次搜索前审计 canonical 快照；同快照 rebuild 不 bump revision。 */
+  async ensureReady() {
+    const snapshot = await this.registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
+    if (snapshot.truncated) {
+      if (await this.search.initialized()) return;
+      throw new TBError("rate_limited", "registry \u8D85\u51FA\u5DE5\u5177\u641C\u7D22 canonical audit \u5BB9\u91CF");
+    }
+    const dirty = await this.dirtyMarkers();
+    await this.rebuildAll(dirty, { canonicalNodes: snapshot.items });
+  }
+  /** 首次 registry/device mutation 前建立 last-known-good，避免并发溢出抢在首次 seed 前。 */
+  async ensureSeeded() {
+    if (await this.search.initialized()) return;
+    if (this.seedPromise === void 0) {
+      this.seedPromise = (async () => {
+        if (!await this.rebuildAll()) {
+          throw new TBError("rate_limited", "registry \u8D85\u51FA\u5DE5\u5177\u641C\u7D22 canonical audit \u5BB9\u91CF");
+        }
+      })();
+    }
+    try {
+      await this.seedPromise;
+    } finally {
+      this.seedPromise = void 0;
+    }
+  }
+  async removeSubtreeQuietly(path, marker) {
+    try {
+      const canonical = normalizeToolSearchPath(path);
+      if ((await this.registry.subtree(canonical)).length === 0) {
+        await this.commitMarker(marker, null);
+        await this.search.removePrefix(canonical);
+        await this.finishMarker(marker);
+      } else {
+        await this.rebuildAll(marker === void 0 ? [] : [marker]);
+      }
+    } catch {
+    }
+  }
+};
+
 // ../app/src/deviceHello.ts
 function assertDeviceId(deviceId) {
   if (!/^[A-Za-z0-9._-]+$/.test(deviceId)) {
@@ -20546,6 +20557,7 @@ function customNodeInput(mountPath, deviceId, raw) {
   return input;
 }
 function nodesForHello(mountPath, deviceId, expose) {
+  const rawTargets = [mountPath];
   const nodes = [
     {
       path: mountPath,
@@ -20554,6 +20566,7 @@ function nodesForHello(mountPath, deviceId, expose) {
     }
   ];
   if (expose.shell !== void 0) {
+    rawTargets.push(joinTreePath(mountPath, "shell"));
     nodes.push({
       path: joinTreePath(mountPath, "shell"),
       kind: "device",
@@ -20562,6 +20575,7 @@ function nodesForHello(mountPath, deviceId, expose) {
     });
   }
   if (expose.fs !== void 0) {
+    rawTargets.push(joinTreePath(mountPath, "fs"));
     nodes.push({
       path: joinTreePath(mountPath, "fs"),
       kind: "context",
@@ -20575,11 +20589,13 @@ function nodesForHello(mountPath, deviceId, expose) {
     });
   }
   for (const raw of expose.nodes ?? []) {
+    rawTargets.push(joinTreePath(mountPath, raw.path));
     nodes.push(customNodeInput(mountPath, deviceId, raw));
   }
+  assertNoCollision(rawTargets, `\u8BBE\u5907 '${deviceId}' \u7684 expose \u8DEF\u5F84`);
   return nodes;
 }
-async function assertRegisterPath(registry, ctx, targetPath) {
+async function assertRegisterPath(registry, ctx, targetPath, reservedRoots) {
   if (!check(ctx, targetPath, "register").allow) {
     throw new TBError("permission_denied", `no scope grants 'register' on '${targetPath}'`);
   }
@@ -20597,7 +20613,8 @@ async function assertRegisterPath(registry, ctx, targetPath) {
     },
     targetPath,
     action: "write",
-    existing
+    existing,
+    ...reservedRoots !== void 0 ? { reservedRoots } : {}
   });
   if (!res.allow) throw res.error;
 }
@@ -20618,7 +20635,7 @@ async function processDeviceHello(opts) {
   const inputs = nodesForHello(mountPath, hello.deviceId, hello.expose);
   const registry = new NodeRegistryStore(store);
   for (const input of inputs) {
-    await assertRegisterPath(registry, authCtx, input.path);
+    await assertRegisterPath(registry, authCtx, input.path, opts.reservedRoots);
     assertSecretRefUse(authCtx.scopes, input.config);
   }
   const now = opts.now ?? (/* @__PURE__ */ new Date()).toISOString();
@@ -20633,7 +20650,7 @@ async function processDeviceHello(opts) {
         input,
         authCtx.keyId,
         now,
-        input.path === mountPath ? { online: true, lastSeenAt: now } : {}
+        input.path === mountPath ? { deviceId: hello.deviceId, online: true, lastSeenAt: now } : {}
       );
     } catch (error) {
       await searchSync?.abort(marker);
@@ -20647,6 +20664,80 @@ async function processDeviceHello(opts) {
   return { mountPath, keyId: authCtx.keyId, searchIndexed };
 }
 
+// ../app/src/deviceLifecycle.ts
+async function reverifyDeviceAuthority(opts) {
+  const authCtx = await identify(opts.store, opts.authorization, (/* @__PURE__ */ new Date()).toISOString());
+  if (authCtx === null || authCtx.keyId !== opts.keyId) return false;
+  return checkRegisterPath({
+    sk: {
+      scopes: authCtx.scopes,
+      id: authCtx.keyId,
+      ...authCtx.registerPaths !== void 0 ? { registerPaths: authCtx.registerPaths } : {}
+    },
+    targetPath: opts.mountPath,
+    action: "write",
+    existing: null,
+    ...opts.reservedRoots !== void 0 ? { reservedRoots: opts.reservedRoots } : {}
+  }).allow;
+}
+async function markDeviceDisconnected(opts) {
+  try {
+    await opts.registry.setOnline(opts.mountPath, false, opts.now);
+  } catch {
+  }
+}
+async function reclaimDeviceSubtree(opts) {
+  const searchSync = opts.search === void 0 ? void 0 : new SearchSynchronizer(opts.state, opts.search);
+  const marker = await searchSync?.markSubtree(opts.mountPath);
+  try {
+    await opts.registry.deleteSubtree(opts.mountPath);
+  } catch {
+  }
+  await searchSync?.removeSubtreeQuietly(opts.mountPath, marker);
+}
+function deviceSearchCapacityWarning(deviceId, mountPath) {
+  return `[tool-bridge] device '${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 tool search until capacity frees up.`;
+}
+
+// ../app/src/deviceMailbox.ts
+var KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS = "sys:device-mailbox-cleanup-progress:v1";
+function parseProgress(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || typeof value.cursor !== "string" || !Number.isSafeInteger(value.revision) || value.revision < 1) throw new TBError("internal", "device mailbox cleanup progress is invalid");
+  return value;
+}
+function createDeviceMailboxService(deps) {
+  return new DeviceMailboxService(deps.state, deps.encryptionKey);
+}
+async function cleanupDeviceMailbox(deps, opts = {}) {
+  await deps.ensureReady?.();
+  if (deps.state.compareAndSwap === void 0) {
+    throw new TBError("unavailable", "device mailbox cleanup requires StateStore.compareAndSwap");
+  }
+  const mailbox = createDeviceMailboxService(deps);
+  const maxPages = Math.min(positiveInt(opts.maxPages, 8, "maxPages"), 64);
+  const limit = Math.min(positiveInt(opts.limit, 200, "limit"), 200);
+  const aggregate = { deleted: 0, expired: 0, scanned: 0 };
+  const cursor = await runCursorCleanup({
+    // {cursor,revision} 即持久形状,原样落库。
+    encodeProgress: (progress) => progress,
+    maxPages,
+    parseProgress,
+    progressKey: KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS,
+    runPage: async (pageCursor) => {
+      const page = await mailbox.cleanup({
+        limit,
+        ...pageCursor === void 0 ? {} : { cursor: pageCursor }
+      });
+      aggregate.deleted += page.deleted;
+      aggregate.expired += page.expired;
+      aggregate.scanned += page.scanned;
+      return page.cursor;
+    },
+    state: deps.state
+  });
+  return { ...aggregate, ...cursor === void 0 ? {} : { cursor } };
+}
+
 // ../../node_modules/.pnpm/@modelcontextprotocol+server@2.0.0/node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
 var __create2 = Object.create;
 var __defProp2 = Object.defineProperty;
@@ -36292,17 +36383,34 @@ function assertSchemaShape(value, path, depth = 0) {
     list.forEach((sub, i) => assertSchemaShape(sub, `${path}/${key}/${i}`, depth + 1));
   }
 }
-function inputSchemaOf(raw) {
-  if (raw === void 0) return { type: "object", properties: {} };
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+function inputSchemaOf(raw, delivery) {
+  if (raw === void 0 && delivery === void 0) return { type: "object", properties: {} };
+  const source = raw ?? { type: "object", properties: {} };
+  if (source === null || typeof source !== "object" || Array.isArray(source)) {
     throw new Error("MCP tool inputSchema must be a JSON Schema object");
   }
-  const schema = raw;
+  const schema = source;
   if (schema.type !== void 0 && schema.type !== "object") {
     throw new Error("MCP tool inputSchema root type must be object");
   }
   assertSchemaShape(schema, "inputSchema");
-  return { ...schema, type: "object" };
+  if (delivery !== "mailbox" && delivery !== "both") {
+    return { ...schema, type: "object" };
+  }
+  const properties = schema.properties;
+  if (properties !== void 0 && (properties === null || typeof properties !== "object" || Array.isArray(properties))) throw new Error("MCP tool inputSchema properties must be an object");
+  return {
+    ...schema,
+    type: "object",
+    properties: {
+      ...properties ?? {},
+      "~delivery": {
+        type: "string",
+        enum: delivery === "both" ? ["realtime", "mailbox", "fallback"] : ["mailbox", "fallback"],
+        description: "Tool Bridge delivery policy; fallback prefers realtime and queues only when dispatch definitely did not occur."
+      }
+    }
+  };
 }
 function annotationsOf(tool) {
   const annotations = {};
@@ -36328,7 +36436,7 @@ async function projectTools(source, validator) {
 HTBP ${bridge.invokePath}`;
       let inputSchema;
       try {
-        inputSchema = inputSchemaOf(bridge.inputSchema);
+        inputSchema = inputSchemaOf(bridge.inputSchema, bridge.delivery);
       } catch {
         throw new ProtocolError3(
           ProtocolErrorCode2.InternalError,
@@ -36706,6 +36814,16 @@ import { Hono } from "hono";
 // ../core/src/protocol/openapi.ts
 var schemaRegistry = external_exports.registry();
 var schemas = {
+  DeviceOperationClaimRequest: deviceOperationClaimRequestSchema,
+  DeviceOperationClaimResponse: deviceOperationClaimResponseSchema,
+  DeviceOperationCompleteRequest: deviceOperationCompleteRequestSchema,
+  DeviceOperationDetail: deviceOperationDetailSchema,
+  DeviceOperationIdentityRequest: deviceOperationIdentityRequestSchema,
+  DeviceOperationListRequest: deviceOperationListRequestSchema,
+  DeviceOperationListResponse: deviceOperationListResponseSchema,
+  DeviceOperationRenewRequest: deviceOperationRenewRequestSchema,
+  DeviceOperationRenewResponse: deviceOperationRenewResponseSchema,
+  DeviceOperationSummary: deviceOperationSummarySchema,
   Error: tbErrorBodySchema,
   FeedbackDetail: feedbackDetailSchema,
   FeedbackList: feedbackListSchema,
@@ -36941,20 +37059,82 @@ var fixedControlPlaneOpenApi = {
         "x-tool-bridge-greedy-path": true
       }
     },
+    "/~device/operations/get": {
+      post: {
+        operationId: "getDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationIdentityRequest") },
+        responses: { 200: jsonResponse("Device operation detail", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
+    "/~device/operations/list": {
+      post: {
+        operationId: "listDeviceOperations",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationListRequest") },
+        responses: { 200: jsonResponse("Visible device operation page", "DeviceOperationListResponse"), ...errorResponses }
+      }
+    },
+    "/~device/operations/cancel": {
+      post: {
+        operationId: "cancelDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationIdentityRequest") },
+        responses: { 200: jsonResponse("Cancelled or cancellation-requested operation", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/claim": {
+      post: {
+        operationId: "claimDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationClaimRequest") },
+        responses: { 200: jsonResponse("Claimed operation or next scan cursor", "DeviceOperationClaimResponse"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/renew": {
+      post: {
+        operationId: "renewDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationRenewRequest") },
+        responses: { 200: jsonResponse("Renewed operation lease", "DeviceOperationRenewResponse"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/complete": {
+      post: {
+        operationId: "completeDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationCompleteRequest") },
+        responses: { 200: jsonResponse("Terminal device operation", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
     "/{commandPath}": {
       post: {
         "operationId": "invoke",
         "security": bearerSecurity,
-        "parameters": [{
-          in: "path",
-          name: "commandPath",
-          required: true,
-          schema: { type: "string" },
-          description: "Complete HTBP command path, including the command/tool leaf."
-        }],
+        "parameters": [
+          {
+            in: "path",
+            name: "commandPath",
+            required: true,
+            schema: { type: "string" },
+            description: "Complete HTBP command path, including the command/tool leaf."
+          },
+          {
+            in: "query",
+            name: "ttlSeconds",
+            schema: { type: "integer", minimum: 1 },
+            description: "Mailbox operation TTL; used only when ~delivery can enqueue."
+          },
+          {
+            in: "header",
+            name: "x-tb-idempotency-key",
+            schema: { type: "string", minLength: 1, maxLength: 255 },
+            description: "Mailbox retry key; used only when ~delivery can enqueue."
+          }
+        ],
         "requestBody": {
           required: true,
-          description: "Raw command arguments; there is no {tool, arguments} envelope.",
+          description: "Raw command arguments plus the reserved optional ~delivery control.",
           content: { "application/json": { schema: {} } }
         },
         "responses": {
@@ -36965,6 +37145,7 @@ var fixedControlPlaneOpenApi = {
               "text/markdown": { schema: { type: "string" } }
             }
           },
+          202: jsonResponse("Durably accepted device operation", "DeviceOperationDetail"),
           ...errorResponses
         },
         "x-tool-bridge-greedy-path": true
@@ -37250,6 +37431,239 @@ function renderTreeDsl(tree) {
 `;
 }
 
+// ../app/src/routes/deviceMailbox.ts
+var DEVICE_MAILBOX_IDEMPOTENCY_HEADER = "x-tb-idempotency-key";
+var DEVICE_MAILBOX_HTTP_BODY_BYTES = 272 * 1024;
+var DEVICE_MAILBOX_LIST_LIMIT_DEFAULT = 50;
+var DEVICE_MAILBOX_LIST_LIMIT_MAX = 200;
+function invalidRequest(message) {
+  return new TBError("invalid_argument", message);
+}
+async function mailboxJsonObject(c, opts = {}) {
+  const declaredLength = Number(c.req.header("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > DEVICE_MAILBOX_HTTP_BODY_BYTES) {
+    throw new TBError("rate_limited", "device mailbox request body is too large", {
+      retryable: false
+    });
+  }
+  const reader = c.req.raw.body?.getReader();
+  let raw = "";
+  if (reader !== void 0) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+    let received = 0;
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        received += chunk.value.byteLength;
+        if (received > DEVICE_MAILBOX_HTTP_BODY_BYTES) {
+          await reader.cancel().catch(() => {
+          });
+          throw new TBError("rate_limited", "device mailbox request body is too large", {
+            retryable: false
+          });
+        }
+        raw += decoder.decode(chunk.value, { stream: true });
+      }
+      raw += decoder.decode();
+    } catch (cause) {
+      if (cause instanceof TBError) throw cause;
+      throw invalidRequest("body must be valid UTF-8 JSON");
+    }
+  }
+  let parsed = opts.allowEmpty === true && raw === "" ? {} : null;
+  if (raw !== "") {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = null;
+    }
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw invalidRequest("body must be a JSON object");
+  }
+  return parsed;
+}
+function parseBody(schema, body) {
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) throw invalidRequest(parsed.error.issues[0]?.message ?? "invalid request");
+  return parsed.data;
+}
+function deviceOperationTtlSeconds(url2) {
+  for (const key of url2.searchParams.keys()) {
+    if (key !== "ttlSeconds") throw invalidRequest(`unknown enqueue query parameter '${key}'`);
+  }
+  const value = url2.searchParams.get("ttlSeconds");
+  if (value === null) return void 0;
+  if (!/^[1-9]\d*$/.test(value)) throw invalidRequest("ttlSeconds must be a positive integer");
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw invalidRequest("ttlSeconds must be a safe integer");
+  return parsed;
+}
+function canManage(ctx, operation) {
+  return ctx.owner === operation.caller.owner || check(ctx, operation.targetPath, "admin").allow;
+}
+function assertCanManage(ctx, operation) {
+  if (!canManage(ctx, operation)) throw TBError.notFound("device operation not found");
+}
+async function assertCurrentDeviceCredential(c, target, reservedRoots) {
+  const ctx = c.get("ctx");
+  if (ctx.keyId !== target.deviceKeyId) {
+    throw new TBError("permission_denied", "device credential does not own this operation");
+  }
+  let existing = null;
+  try {
+    existing = await new NodeRegistryStore(c.get("store")).get(target.mountPath);
+  } catch {
+    existing = null;
+  }
+  const allowed = checkRegisterPath({
+    action: "write",
+    existing,
+    sk: {
+      id: ctx.keyId,
+      scopes: ctx.scopes,
+      ...ctx.registerPaths === void 0 ? {} : { registerPaths: ctx.registerPaths }
+    },
+    targetPath: target.mountPath,
+    ...reservedRoots === void 0 ? {} : { reservedRoots }
+  });
+  if (!allowed.allow) throw allowed.error;
+}
+async function enqueueDeviceCommand(c, env, input) {
+  const { arguments: args, command, marker, node } = input;
+  const ctx = c.get("ctx");
+  const result = await env.mailbox().enqueue({
+    arguments: args,
+    caller: { keyId: ctx.keyId, owner: ctx.owner },
+    deviceId: marker.deviceId,
+    deviceKeyId: node.registeredBy,
+    mountPath: marker.mountPath,
+    // 管理面与审计链必须能区分同一 tool 节点下的不同命令；权限仍按前缀 scope 判定。
+    targetPath: `${node.path}/${command}`,
+    path: `${relativeDevicePath(node.path, marker.mountPath)}/${command}`,
+    traceId: ctx.traceId,
+    ...c.req.header(DEVICE_MAILBOX_IDEMPOTENCY_HEADER) === void 0 ? {} : { idempotencyKey: c.req.header(DEVICE_MAILBOX_IDEMPOTENCY_HEADER) },
+    ...input.ttlSeconds === void 0 ? {} : { ttlSeconds: input.ttlSeconds }
+  });
+  const response = c.json(deviceOperationDetailSchema.parse(result), 202);
+  response.headers.set("x-tb-delivery", "mailbox");
+  return response;
+}
+async function getOperation(c, env) {
+  const input = parseBody(deviceOperationIdentityRequestSchema, await mailboxJsonObject(c));
+  const result = await env.mailbox().get(input.deviceId, input.operationId);
+  assertCanManage(c.get("ctx"), result);
+  return c.json(deviceOperationDetailSchema.parse(result));
+}
+async function listOperations(c, env) {
+  const input = parseBody(deviceOperationListRequestSchema, await mailboxJsonObject(c));
+  const mailbox = env.mailbox();
+  const ctx = c.get("ctx");
+  const limit = Math.min(
+    input.opts?.limit ?? DEVICE_MAILBOX_LIST_LIMIT_DEFAULT,
+    DEVICE_MAILBOX_LIST_LIMIT_MAX
+  );
+  let cursor = input.opts?.cursor;
+  const items = [];
+  while (items.length < limit) {
+    const previous = cursor;
+    const page = await mailbox.list({
+      deviceId: input.deviceId,
+      limit: limit - items.length,
+      ...cursor === void 0 ? {} : { cursor },
+      ...input.opts?.states === void 0 ? {} : { states: input.opts.states }
+    });
+    items.push(...page.items.filter((item) => canManage(ctx, item)));
+    cursor = page.cursor;
+    if (cursor === void 0) {
+      return c.json(deviceOperationListResponseSchema.parse({ items }));
+    }
+    if (cursor === previous) {
+      throw new TBError("internal", "device mailbox list cursor did not advance");
+    }
+  }
+  const resumeCursor = cursor;
+  if (resumeCursor === void 0) {
+    return c.json(deviceOperationListResponseSchema.parse({ items }));
+  }
+  let probeCursor = resumeCursor;
+  while (probeCursor !== void 0) {
+    const previous = probeCursor;
+    const page = await mailbox.list({
+      deviceId: input.deviceId,
+      cursor: probeCursor,
+      limit: DEVICE_MAILBOX_LIST_LIMIT_MAX,
+      ...input.opts?.states === void 0 ? {} : { states: input.opts.states }
+    });
+    if (page.items.some((item) => canManage(ctx, item))) {
+      return c.json(deviceOperationListResponseSchema.parse({ items, cursor: resumeCursor }));
+    }
+    probeCursor = page.cursor;
+    if (probeCursor === previous) {
+      throw new TBError("internal", "device mailbox list cursor did not advance");
+    }
+  }
+  return c.json(deviceOperationListResponseSchema.parse({ items }));
+}
+async function cancelOperation(c, env) {
+  const input = parseBody(deviceOperationIdentityRequestSchema, await mailboxJsonObject(c));
+  const mailbox = env.mailbox();
+  const current = await mailbox.get(input.deviceId, input.operationId);
+  assertCanManage(c.get("ctx"), current);
+  return c.json(deviceOperationDetailSchema.parse(
+    await mailbox.cancel(input.deviceId, input.operationId)
+  ));
+}
+function deviceAuthorize(c, env) {
+  return async (target) => await assertCurrentDeviceCredential(c, target, env.deps.reservedRoots);
+}
+async function claimOperations(c, env) {
+  const input = parseBody(deviceOperationClaimRequestSchema, await mailboxJsonObject(c));
+  return c.json(deviceOperationClaimResponseSchema.parse(await env.mailbox().claim({
+    ...input,
+    deviceKeyId: c.get("ctx").keyId,
+    authorize: deviceAuthorize(c, env)
+  })));
+}
+async function renewLeases(c, env) {
+  const input = parseBody(deviceOperationRenewRequestSchema, await mailboxJsonObject(c));
+  return c.json(deviceOperationRenewResponseSchema.parse(await env.mailbox().renew({
+    ...input,
+    deviceKeyId: c.get("ctx").keyId,
+    authorize: deviceAuthorize(c, env)
+  })));
+}
+async function completeOperation(c, env) {
+  const input = parseBody(deviceOperationCompleteRequestSchema, await mailboxJsonObject(c));
+  let completion;
+  if (input.outcome === "succeeded") {
+    completion = { outcome: "succeeded", result: input.result };
+  } else if (input.outcome === "result_unknown") {
+    completion = {
+      outcome: "result_unknown",
+      ...input.error === void 0 ? {} : { error: input.error }
+    };
+  } else {
+    completion = { outcome: input.outcome, error: input.error };
+  }
+  return c.json(deviceOperationDetailSchema.parse(await env.mailbox().complete({
+    deviceId: input.deviceId,
+    operationId: input.operationId,
+    leaseId: input.leaseId,
+    deviceKeyId: c.get("ctx").keyId,
+    authorize: deviceAuthorize(c, env)
+  }, completion)));
+}
+function registerDeviceMailboxRoutes(app, env) {
+  app.post("/~device/operations/get", (c) => runHandler(async () => await getOperation(c, env)));
+  app.post("/~device/operations/list", (c) => runHandler(async () => await listOperations(c, env)));
+  app.post("/~device/operations/cancel", (c) => runHandler(async () => await cancelOperation(c, env)));
+  app.post("/~device/mailbox/claim", (c) => runHandler(async () => await claimOperations(c, env)));
+  app.post("/~device/mailbox/renew", (c) => runHandler(async () => await renewLeases(c, env)));
+  app.post("/~device/mailbox/complete", (c) => runHandler(async () => await completeOperation(c, env)));
+}
+
 // ../app/src/federation.ts
 var SEARCH_REMAINING_MS_HEADER = "x-tb-search-remaining-ms";
 function remoteProtocolError(message) {
@@ -37471,6 +37885,24 @@ function assertRemoteConfigAllowed(config, settings) {
   assertRemoteAllowed(baseUrl, settings);
 }
 
+// ../app/src/registryMutation.ts
+async function assertNodeConfigMutation(opts) {
+  const { action, config, ctx, deps, registry, targetPath } = opts;
+  assertRemoteConfigAllowed(config, await resolveRemoteSettings(deps.state, deps.remote));
+  await assertRegisterPath2(registry, ctx, targetPath, action, deps);
+  assertSecretRefUse(ctx.scopes, config);
+  await assertMcpOAuthConfig(config, deps.secrets);
+  await assertContextConfig(config, deps);
+  await assertSkillhubConfig(config, deps);
+  await assertToolConfig(config, deps, ctx, targetPath);
+}
+async function invalidateNodeDerivedState(store, path) {
+  await invalidateToolCache(store, path);
+  await invalidateMcpEra(store, path);
+  await invalidateMcpOAuth(store, path);
+  await invalidateProviderOAuth(store, path);
+}
+
 // ../app/src/routes/register.ts
 async function authorizeToolNode(c, env, node, encryptionKey) {
   const { deps } = env;
@@ -37527,16 +37959,17 @@ async function handleRegister(c, env) {
     );
   }
   const body = parseNodeInput(raw);
-  assertRemoteConfigAllowed(body.config, await resolveRemoteSettings(store, deps.remote));
   if (!check(ctx, path, "register").allow) {
     throw new TBError("permission_denied", `no scope grants 'register' on '${path}'`);
   }
-  await assertRegisterPath2(registry, ctx, body.path, "write", deps);
-  assertSecretRefUse(ctx.scopes, body.config);
-  await assertMcpOAuthConfig(body.config, deps.secrets);
-  await assertContextConfig(body.config, deps);
-  await assertSkillhubConfig(body.config, deps);
-  await assertToolConfig(body.config, deps, ctx, body.path);
+  await assertNodeConfigMutation({
+    action: "write",
+    config: body.config,
+    ctx,
+    deps,
+    registry,
+    targetPath: body.path
+  });
   await searchSync?.ensureSeeded();
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const marker = await searchSync?.markNode(body.path);
@@ -37547,12 +37980,9 @@ async function handleRegister(c, env) {
     await searchSync?.abort(marker);
     throw error;
   }
-  await invalidateToolCache(store, body.path);
-  await invalidateMcpEra(store, body.path);
-  await invalidateMcpOAuth(store, body.path);
-  await invalidateProviderOAuth(store, body.path);
+  await invalidateNodeDerivedState(store, body.path);
   await searchSync?.reconcileNodeQuietly(body.path, { marker });
-  if (await refreshDynamicSearchNode(node, ctx, deps)) await searchSync?.abort(marker);
+  if (await refreshDynamicSearchNode(node, ctx, deps, searchSync)) await searchSync?.abort(marker);
   return new Response(JSON.stringify(registryNodeSchema.parse(node)), {
     headers: { "content-type": contentTypeFor("json") }
   });
@@ -37649,7 +38079,7 @@ async function handleDescribe(c, env) {
     await assertContextAlive(node, node.config, registry);
     const cfg = node.config;
     const local = cfg.provider !== "r2" && cfg.provider !== "s3" ? localContext(deps, node) : null;
-    let capabilities = cfg.provider === "r2" || cfg.provider === "s3" || cfg.provider === "device-fs" || deviceMarkerOf(cfg.providerConfig) !== null ? CONTEXT_CAPABILITIES : local !== null ? localCapabilities(local) : (await requirePluginExport(deps, cfg.provider, "context", "context", cfg.export)).export.capabilities ?? [];
+    let capabilities = cfg.provider === "r2" || cfg.provider === "s3" || cfg.provider === "device-fs" || deviceMarkerOf(cfg.providerConfig) !== null ? CONTEXT_CAPABILITIES : local !== null ? contextCapabilitiesOf(local) : (await requirePluginExport(deps, cfg.provider, "context", "context", cfg.export)).export.capabilities ?? [];
     if ((cfg.provider === "r2" || cfg.provider === "s3") && cfg.readOnly !== true && await contextDirectUploadAvailable(cfg, deps)) {
       capabilities = [...capabilities, CONTEXT_DIRECT_UPLOAD_CAPABILITY];
     }
@@ -38317,12 +38747,8 @@ var FederatedSearchSessionStore = class {
   }
 };
 
-// ../app/src/search/localSearch.ts
-function normalizedEffect(effect) {
-  return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
-}
-function projectSearchTool(tool, detail) {
-  if (detail === "full") return tool;
+// ../app/src/search/compactTool.ts
+function compactSearchTool(tool) {
   const compact = { ...tool };
   delete compact.inputSchema;
   delete compact.outputSchema;
@@ -38342,6 +38768,14 @@ function projectSearchTool(tool, detail) {
   }
   return compact;
 }
+
+// ../app/src/search/localSearch.ts
+function normalizedEffect(effect) {
+  return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
+}
+function projectSearchTool(tool, detail) {
+  return detail === "full" ? tool : compactSearchTool(tool);
+}
 async function executeLocalSearch(deps, request) {
   const { ctx, search, searchSync, state } = deps;
   const query = request.query;
@@ -38497,24 +38931,7 @@ function continuationSourceError(error) {
   return retryableContinuationError();
 }
 function compactItem(item) {
-  const tool = { ...item.tool };
-  delete tool.inputSchema;
-  delete tool.outputSchema;
-  if (tool.description !== void 0) {
-    const encoder = new TextEncoder();
-    if (encoder.encode(tool.description).length > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) {
-      let description = "";
-      let bytes = 0;
-      for (const char of tool.description) {
-        const size = encoder.encode(char).length;
-        if (bytes + size > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) break;
-        description += char;
-        bytes += size;
-      }
-      tool.description = description;
-    }
-  }
-  return { ...item, tool };
+  return { ...item, tool: compactSearchTool(item.tool) };
 }
 function normalizedEffect2(effect) {
   return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
@@ -39214,9 +39631,6 @@ async function executeFederatedSearch(deps, input) {
       "recursive search requires explicit TB_INSTANCE_ID and atomic StateStore CAS"
     );
   }
-  if ((input.request.opts?.mode ?? "keyword") !== "keyword") {
-    throw new TBError("invalid_argument", "semantic search cannot use recursive federation");
-  }
   const wireOpts = input.request.opts ?? {};
   const constraints = normalizeToolSearchOptions({
     ...wireOpts.effects === void 0 ? {} : { effects: wireOpts.effects },
@@ -39529,13 +39943,6 @@ function registerSearchRoute(app, env) {
         );
       }
       const request = requestWithNormalizedLimit(parsed.data);
-      const mode = request.opts?.mode ?? "keyword";
-      if (mode === "semantic" && !capabilities.includes("search:semantic")) {
-        throw new TBError(
-          "invalid_argument",
-          "search mode 'semantic' requires capability 'search:semantic'"
-        );
-      }
       const explicitFederation = request.opts?.federation;
       const cursor = request.opts?.cursor;
       const federation = explicitFederation ?? (cursor !== void 0 && !isFederatedSearchSessionHandle(cursor) ? "local" : capabilities.includes("search:federated") ? "recursive" : "local");
@@ -39545,9 +39952,6 @@ function registerSearchRoute(app, env) {
           "recursive search requires capability 'search:federated'"
         );
       }
-      if (federation === "recursive" && mode === "semantic") {
-        throw new TBError("invalid_argument", "semantic search cannot use recursive federation");
-      }
       const normalizedRequest = {
         ...request,
         opts: { ...request.opts ?? {}, federation }
@@ -39615,7 +40019,7 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
   }
   if (node.kind === "mcp" || node.kind === "http" || node.kind === "tool") {
     const provider = await providerFor(node, ctx, deps);
-    const raw = await upstreamTools(node, provider, deps, opts.refresh, opts.now);
+    const raw = await upstreamTools(node, provider, deps, opts.refresh, opts.now, opts.searchSync);
     const { exposed } = virtualizeTools(node.virtualize, raw);
     return toolsToHelpModel(
       node.path,
@@ -39685,7 +40089,8 @@ async function commandHelpModelFor(registry, ctx, builtins, deps, path, opts) {
   const full = await helpModelFor(node, registry, ctx, builtins, deps, {
     refresh: opts.refresh,
     schemas: true,
-    now: (/* @__PURE__ */ new Date()).toISOString()
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    searchSync: opts.searchSync
   });
   const cmd = full.cmds.find((c) => c.name === command);
   if (cmd === void 0) return null;
@@ -39711,6 +40116,7 @@ var mcpCommand = (nodePath, nodeDescription, command) => {
     invokePath,
     description: command.h ?? nodeDescription,
     ...command.inputSchema !== void 0 ? { inputSchema: command.inputSchema } : {},
+    ...command.delivery !== void 0 ? { delivery: command.delivery } : {},
     ...command.effect !== void 0 ? { effect: command.effect } : {},
     ...command.confirm === true ? { confirm: true } : {}
   };
@@ -39725,24 +40131,13 @@ var toolSpecCommand = (node, tool, providerBacked = false) => {
     ...providerBacked ? { providerBacked: true } : {},
     description: tool.description ?? node.description,
     ...tool.inputSchema !== void 0 ? { inputSchema: tool.inputSchema } : {},
+    ...tool.delivery !== void 0 ? { delivery: tool.delivery } : {},
     ...tool.effect !== void 0 ? { effect: tool.effect } : {},
     ...tool.confirm === true ? { confirm: true } : {}
   };
 };
-var remoteCommand = (localNodePath, model, command) => {
-  const remoteNodePath = model.node.path.replace(/^\/+|\/+$/g, "");
-  const remoteCommandPath = command.path.replace(/^\/+|\/+$/g, "");
-  if (remoteCommandPath !== remoteNodePath && !remoteCommandPath.startsWith(`${remoteNodePath}/`)) {
-    throw new TBError("unavailable", "remote ~help returned a command outside its node");
-  }
-  const suffix = remoteCommandPath.slice(remoteNodePath.length);
-  return mcpCommand(localNodePath, model.node.description, {
-    ...command,
-    path: `/${localNodePath}${suffix}`
-  });
-};
 function mcpBridgeFor(c, env, app) {
-  const { builtinsOf, deps, globalSearchCapabilities } = env;
+  const { builtinsOf, deps, globalSearchCapabilities, searchSync } = env;
   const ctx = c.get("ctx");
   const registry = new NodeRegistryStore(c.get("store"));
   let remoteRequests = 0;
@@ -39761,7 +40156,7 @@ function mcpBridgeFor(c, env, app) {
         additionalProperties: false,
         properties: {
           query: { type: "string", minLength: 1 },
-          mode: { type: "string", enum: ["keyword", "semantic"] },
+          mode: { type: "string", enum: ["keyword"] },
           limit: { type: "integer", minimum: 1, maximum: 200 },
           cursor: { type: "string", minLength: 1 },
           detail: { type: "string", enum: ["compact", "full"], default: "compact" },
@@ -39829,6 +40224,10 @@ function mcpBridgeFor(c, env, app) {
   };
   const remoteHelp = async (path) => {
     takeRemoteRequest();
+    const projector = await remotePathProjectorIfMatch(registry, path);
+    if (projector === null) {
+      throw remoteProtocolError(`remote ~help path '${path}' lost its mount owner`);
+    }
     const headers = new Headers(c.req.raw.headers);
     headers.set("accept", "application/json");
     const response = await remotePassthroughIfMatch(
@@ -39843,28 +40242,11 @@ function mcpBridgeFor(c, env, app) {
     if (response === null || !response.ok) {
       throw new TBError("unavailable", `remote ~help failed for '${path}'`, { retryable: true });
     }
-    const model = await response.json().catch(() => null);
-    if (model === null || !Array.isArray(model.cmds) || typeof model.node?.path !== "string") {
+    const parsed = helpJsonSchema.safeParse(await response.json().catch(() => null));
+    if (!parsed.success) {
       throw new TBError("unavailable", `remote ~help returned invalid JSON for '${path}'`);
     }
-    const owner = await registry.resolve(path).catch(() => null);
-    if (owner?.node.kind !== "remote") {
-      throw remoteProtocolError(`remote ~help path '${path}' lost its mount owner`);
-    }
-    const modelPath = canonicalRemotePath(model.node.path, true);
-    if (modelPath !== owner.rest) {
-      throw remoteProtocolError(`remote ~help path '${modelPath}' does not match request`);
-    }
-    for (const command of model.cmds) {
-      if (!command.path.startsWith("/") || command.path.startsWith("//")) {
-        throw remoteProtocolError(`remote ~help returned invalid command path '${command.path}'`);
-      }
-      const commandPath = canonicalRemotePath(command.path.slice(1), true);
-      if (!remotePathWithin(modelPath, commandPath)) {
-        throw remoteProtocolError(`remote ~help command '${command.path}' escapes its node`);
-      }
-    }
-    return model;
+    return projector.projectHelp(parsed.data, path, ctx);
   };
   const remotePaths = async (root) => {
     const found = [];
@@ -39913,13 +40295,10 @@ function mcpBridgeFor(c, env, app) {
             if (check(ctx, path, command.scope).allow) {
               let detailed = command;
               if (command.inputSchema === void 0 && command.path !== `/${model2.node.path}`) {
-                const remoteNodePath = model2.node.path.replace(/^\/+|\/+$/g, "");
-                const remoteCommandPath = command.path.replace(/^\/+|\/+$/g, "");
-                const detailPath = `${path}${remoteCommandPath.slice(remoteNodePath.length)}`;
-                const detail = await remoteHelp(detailPath);
+                const detail = await remoteHelp(command.path.replace(/^\/+/, ""));
                 detailed = detail.cmds.find((item) => item.name === command.name) ?? command;
               }
-              result.push(remoteCommand(path, model2, detailed));
+              result.push(mcpCommand(path, model2.node.description, detailed));
             }
           }
         }
@@ -39935,7 +40314,7 @@ function mcpBridgeFor(c, env, app) {
       if ((node.kind === "mcp" || node.kind === "http" || node.kind === "tool") && node.config !== void 0) {
         if (!check(ctx, node.path, "call").allow) continue;
         const provider = await providerFor(node, ctx, deps);
-        const raw = await upstreamTools(node, provider, deps, false, now);
+        const raw = await upstreamTools(node, provider, deps, false, now, searchSync);
         const { exposed } = virtualizeTools(node.virtualize, raw);
         result.push(...exposed.map((tool) => toolSpecCommand(node, tool, true)));
         continue;
@@ -39943,7 +40322,8 @@ function mcpBridgeFor(c, env, app) {
       const model = await helpModelFor(node, registry, ctx, builtinsOf(c.get("store")), deps, {
         includeDirectUpload: check(ctx, node.path, "write").allow,
         refresh: false,
-        now
+        now,
+        searchSync
       });
       for (const command of model.cmds) {
         if (check(ctx, node.path, command.scope).allow) {
@@ -40046,13 +40426,13 @@ function mcpBridgeFor(c, env, app) {
           throw TBError.notFound("not found");
         }
         const provider = await providerFor(node, ctx, deps);
-        const raw = await upstreamTools(node, provider, deps, false, (/* @__PURE__ */ new Date()).toISOString());
+        const raw = await upstreamTools(node, provider, deps, false, (/* @__PURE__ */ new Date()).toISOString(), searchSync);
         const upstreamName = resolveUpstreamTool(node.virtualize, raw, tool.toolName);
-        const result = await provider.call(upstreamName, args);
+        const result2 = await provider.call(upstreamName, args);
         return {
-          content: result.contentBlocks ?? result.content,
-          ...result.isError === true ? { isError: true } : {},
-          ...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+          content: result2.contentBlocks ?? result2.content,
+          ...result2.isError === true ? { isError: true } : {},
+          ...result2.structuredContent !== void 0 ? { structuredContent: result2.structuredContent } : {}
         };
       }
       const url2 = new URL(tool.invokePath, c.req.url);
@@ -40064,7 +40444,13 @@ function mcpBridgeFor(c, env, app) {
       const response = await app.request(
         new Request(url2, { method: "POST", headers, body: JSON.stringify(args) })
       );
-      return await resultFromResponse(response);
+      const result = await resultFromResponse(response);
+      if (args["~delivery"] !== void 0 && response.ok) {
+        return {
+          content: response.status === 202 ? { delivery: "mailbox", operation: result.content } : { delivery: "realtime", result: result.content }
+        };
+      }
+      return result;
     }
   };
 }
@@ -40099,26 +40485,102 @@ async function handleInvoke(c, env) {
   const node = resolved.node;
   const command = resolved.rest;
   if (!check(ctx, node.path, "read").allow) throw TBError.notFound("not found");
+  const toolMarker = deviceToolMarker(node);
+  let invokeRequest;
+  const readInvokeRequest = async () => {
+    if (invokeRequest !== void 0) return await invokeRequest;
+    invokeRequest = (async () => {
+      const parsed = toolMarker === null ? await c.req.json().catch(() => null) : await mailboxJsonObject(c, { allowEmpty: true });
+      if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
+        throw new TBError("invalid_argument", "body must be a JSON object (command arguments)");
+      }
+      const raw2 = { ...parsed ?? {} };
+      const unknownControls = Object.keys(raw2).filter(
+        (key) => key.startsWith("~") && key !== "~delivery"
+      );
+      if (unknownControls.length > 0) {
+        throw new TBError(
+          "invalid_argument",
+          `unknown invocation control '${unknownControls[0]}'`
+        );
+      }
+      const rawDelivery = raw2["~delivery"];
+      delete raw2["~delivery"];
+      if (rawDelivery !== void 0 && rawDelivery !== "realtime" && rawDelivery !== "mailbox" && rawDelivery !== "fallback") {
+        throw new TBError(
+          "invalid_argument",
+          "'~delivery' must be one of realtime, mailbox, fallback"
+        );
+      }
+      return {
+        arguments: raw2,
+        delivery: rawDelivery ?? "realtime",
+        explicitDelivery: rawDelivery !== void 0
+      };
+    })();
+    return await invokeRequest;
+  };
   const readInvokeBody = async () => {
-    const parsed = await c.req.json().catch(() => null);
-    if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
-      throw new TBError("invalid_argument", "body must be a JSON object (command arguments)");
+    const request = await readInvokeRequest();
+    if (request.explicitDelivery) {
+      throw new TBError(
+        "invalid_argument",
+        "'~delivery' is only supported by device-backed tool commands"
+      );
     }
-    return parsed ?? {};
+    return request.arguments;
   };
-  const toolMarker = deviceToolMarker(node);
   if (toolMarker !== null) {
     if (!check(ctx, node.path, "call").allow) {
       throw new TBError("permission_denied", `no scope grants 'call' on '${node.path}'`);
     }
-    const args2 = await readInvokeBody();
-    const result2 = await invokeDevice(deps, toolMarker.deviceId, {
+    const declared = toolMarker.cmds?.find((item) => item.name.toLowerCase() === command);
+    if (toolMarker.cmds !== void 0 && declared === void 0) throw TBError.notFound("not found");
+    const request = await readInvokeRequest();
+    const capability = declared?.delivery ?? "realtime";
+    const canRealtime = capability === "realtime" || capability === "both";
+    const canMailbox = capability === "mailbox" || capability === "both";
+    if (request.delivery === "realtime" && !canRealtime) {
+      throw new TBError("invalid_argument", "device command does not support realtime delivery");
+    }
+    if (request.delivery === "mailbox" && !canMailbox) {
+      throw new TBError("invalid_argument", "device command does not support mailbox delivery");
+    }
+    if (request.delivery === "fallback" && !canMailbox) {
+      throw new TBError("invalid_argument", "device command does not support mailbox fallback");
+    }
+    const ttlSeconds = request.delivery === "realtime" ? void 0 : deviceOperationTtlSeconds(new URL(c.req.url));
+    const enqueue = async () => await enqueueDeviceCommand(c, env, {
+      arguments: request.arguments,
+      command,
+      marker: toolMarker,
+      node,
+      ...ttlSeconds === void 0 ? {} : { ttlSeconds }
+    });
+    if (request.delivery === "mailbox" || !canRealtime) return await enqueue();
+    if (request.delivery === "fallback" && deps.device === void 0) return await enqueue();
+    const attempt2 = await attemptDevice(deps, toolMarker.deviceId, {
       // 帧 path 含命令叶子段:<mount 相对路径>/<命令>。
       path: `${relativeDevicePath(node.path, toolMarker.mountPath)}/${command}`,
-      arguments: args2,
+      arguments: request.arguments,
       context: deviceCallContextFrom(ctx)
     });
-    return renderResult(result2, negotiate(c.req.header("accept")));
+    if (attempt2.disposition === "not_dispatched" && request.delivery === "fallback") {
+      return await enqueue();
+    }
+    if (attempt2.result.ok) {
+      const response = renderResult(attempt2.result.value, negotiate(c.req.header("accept")));
+      response.headers.set("x-tb-delivery", "realtime");
+      return response;
+    }
+    if (attempt2.disposition === "unknown" && request.delivery === "fallback") {
+      throw new TBError(
+        attempt2.result.error.code,
+        `${attempt2.result.error.message}; delivery outcome is unknown and was not enqueued`,
+        { retryable: false }
+      );
+    }
+    throw tbErrorFromBody(attempt2.result.error);
   }
   if ((node.kind === "mcp" || node.kind === "http" || node.kind === "tool") && node.config !== void 0) {
     if (!check(ctx, node.path, "call").allow) {
@@ -40126,7 +40588,7 @@ async function handleInvoke(c, env) {
     }
     const args2 = await readInvokeBody();
     const provider = await providerFor(node, ctx, deps);
-    const tools = await upstreamTools(node, provider, deps, false, (/* @__PURE__ */ new Date()).toISOString());
+    const tools = await upstreamTools(node, provider, deps, false, (/* @__PURE__ */ new Date()).toISOString(), searchSync);
     const upstreamName = resolveUpstreamTool(node.virtualize, tools, command);
     const result2 = await provider.call(upstreamName, args2);
     return renderResult(result2.content, negotiate(c.req.header("accept")));
@@ -40190,7 +40652,7 @@ async function handleInvoke(c, env) {
     if (cfg.provider !== "r2" && cfg.provider !== "s3") {
       const local = localContext(deps, node);
       if (local !== null) {
-        const result4 = await dispatchContextCmd2(local, command, args2);
+        const result4 = await dispatchContextCmd(local, command, args2);
         return renderResult(result4, negotiate(c.req.header("accept")));
       }
       const { manifest, export: exported } = await requirePluginExport(
@@ -40210,11 +40672,11 @@ async function handleInvoke(c, env) {
         ...cfg.authRef !== void 0 ? { upstreamAuthRef: cfg.authRef } : {},
         ...deps.pluginBindings !== void 0 ? { bindings: deps.pluginBindings } : {}
       });
-      const result3 = await dispatchContextCmd2(provider2, command, args2);
+      const result3 = await dispatchContextCmd(provider2, command, args2);
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
     const provider = await contextProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchContextCmd2(provider, command, args2);
+    const result2 = await dispatchContextCmd(provider, command, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind === "skillhub" && node.config?.kind === "skillhub") {
@@ -40232,7 +40694,7 @@ async function handleInvoke(c, env) {
       throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${command}'`);
     }
     const provider = await skillhubProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchSkillhubCmd2(provider, command, args2);
+    const result2 = await dispatchSkillhubCmd(provider, command, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind !== "builtin" || node.config?.kind !== "builtin") {
@@ -40256,19 +40718,14 @@ async function handleInvoke(c, env) {
       throw new TBError("invalid_argument", "field 'path' must be a string");
     }
     const cfgPatch = cmd === "write" ? args.config : cmd === "update" ? args.patch?.config : void 0;
-    assertRemoteConfigAllowed(cfgPatch, await resolveRemoteSettings(store, deps.remote));
-    await assertRegisterPath2(
-      registry,
+    await assertNodeConfigMutation({
+      action: cmd === "delete" ? "delete" : "write",
+      config: cfgPatch,
       ctx,
-      targetPath,
-      cmd === "delete" ? "delete" : "write",
-      deps
-    );
-    assertSecretRefUse(ctx.scopes, cfgPatch);
-    await assertMcpOAuthConfig(cfgPatch, deps.secrets);
-    await assertContextConfig(cfgPatch, deps);
-    await assertSkillhubConfig(cfgPatch, deps);
-    await assertToolConfig(cfgPatch, deps, ctx, targetPath);
+      deps,
+      registry,
+      targetPath
+    });
     registryTarget = targetPath;
   }
   if (registryTarget !== void 0 && (cmd === "write" || cmd === "update")) {
@@ -40298,22 +40755,16 @@ async function handleInvoke(c, env) {
     return tbErrorResponse(new TBError("internal", "internal error"));
   }
   if (registryTarget !== void 0) {
-    await invalidateToolCache(store, registryTarget);
-    await invalidateMcpEra(store, registryTarget);
-    await invalidateMcpOAuth(store, registryTarget);
-    await invalidateProviderOAuth(store, registryTarget);
+    await invalidateNodeDerivedState(store, registryTarget);
     await searchSync?.reconcileNodeQuietly(registryTarget, { marker: registryMarker });
     const current = await registry.get(registryTarget).catch(() => null);
-    if (current !== null && await refreshDynamicSearchNode(current, ctx, deps)) {
+    if (current !== null && await refreshDynamicSearchNode(current, ctx, deps, searchSync)) {
       await searchSync?.abort(registryMarker);
     }
   }
   const pluginEmptyPaths = [];
   for (const mount of pluginMounts) {
-    await invalidateToolCache(store, mount.node.path);
-    await invalidateMcpEra(store, mount.node.path);
-    await invalidateMcpOAuth(store, mount.node.path);
-    await invalidateProviderOAuth(store, mount.node.path);
+    await invalidateNodeDerivedState(store, mount.node.path);
     const providerId = mount.node.config?.kind === "tool" ? mount.node.config.provider : "";
     const manifest = await store.get(KEY_PLUGIN + providerId);
     if (manifest !== null && manifest.enabled !== false) {
@@ -40361,8 +40812,7 @@ function createRouteEnv(deps) {
     if (!declared.has("search")) return [];
     return [
       "search",
-      ...deps.remote.instanceId !== void 0 && deps.state.compareAndSwap !== void 0 && deps.search?.revision !== void 0 ? ["search:federated"] : [],
-      ...declared.has("search:semantic") ? ["search:semantic"] : []
+      ...deps.remote.instanceId !== void 0 && deps.state.compareAndSwap !== void 0 && deps.search?.revision !== void 0 ? ["search:federated"] : []
     ];
   };
   let catalogDigest;
@@ -40372,12 +40822,17 @@ function createRouteEnv(deps) {
     catalogDigest ??= catalogSetDigest(catalog);
     return catalogDigest;
   };
-  return { builtinsOf, deps, globalSearchCapabilities, pluginCatalogDigest, searchSync };
+  let mailboxInstance;
+  const mailbox = () => {
+    mailboxInstance ??= createDeviceMailboxService(deps);
+    return mailboxInstance;
+  };
+  return { builtinsOf, deps, globalSearchCapabilities, mailbox, pluginCatalogDigest, searchSync };
 }
 
 // ../app/src/routes/help.ts
 async function handleHelp(c, env) {
-  const { builtinsOf, deps } = env;
+  const { builtinsOf, deps, searchSync } = env;
   const path = splitReserved(new URL(c.req.url).pathname, "~help");
   if (path === null) throw TBError.notFound("no such path");
   const ctx = c.get("ctx");
@@ -40416,11 +40871,12 @@ async function handleHelp(c, env) {
   try {
     node = await registry.get(path);
   } catch {
-    const toolModel = await toolHelpModelFor(c, ctx, registry, path, deps);
+    const toolModel = await toolHelpModelFor(c, ctx, registry, path, deps, searchSync);
     if (toolModel !== null) return renderHelp(await enrichHelp(toolModel, path, store), rep);
     const cmdModel = await commandHelpModelFor(registry, ctx, builtins, deps, path, {
       refresh,
-      schemas: schemas2
+      schemas: schemas2,
+      searchSync
     });
     if (cmdModel !== null) return renderHelp(await enrichHelp(cmdModel, path, store), rep);
     throw TBError.notFound("not found");
@@ -40428,7 +40884,8 @@ async function handleHelp(c, env) {
   const model = await helpModelFor(node, registry, ctx, builtins, deps, {
     refresh,
     schemas: schemas2,
-    now: (/* @__PURE__ */ new Date()).toISOString()
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    searchSync
   });
   return renderHelp(await enrichHelp(model, path, store), rep);
 }
@@ -40536,6 +40993,7 @@ function createTbApp(deps) {
   });
   registerMcpRoute(app, env);
   registerSearchRoute(app, env);
+  registerDeviceMailboxRoutes(app, env);
   app.get(
     "/system/device/ws",
     (c) => runHandler(async () => {
@@ -40666,7 +41124,10 @@ var DeviceHub = class {
    */
   async invoke(deviceId, req) {
     if (this.activeByDevice.has(deviceId)) return await this.invokeLocal(deviceId, req);
-    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    const offline = {
+      disposition: "not_dispatched",
+      result: { ok: false, error: TBError.deviceOffline().toJSON() }
+    };
     if (this.router === void 0) return offline;
     return await this.router.forward(deviceId, req) ?? offline;
   }
@@ -40677,26 +41138,27 @@ var DeviceHub = class {
    * 那会再次查路由并转发,在两个副本间弹来弹去。这里没有连接就直接 offline。
    */
   async invokeLocal(deviceId, req) {
-    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    const offline = {
+      disposition: "not_dispatched",
+      result: { ok: false, error: TBError.deviceOffline().toJSON() }
+    };
     const conn = this.activeByDevice.get(deviceId);
     if (conn === void 0) return offline;
-    const authCtx = await identify(this.store, conn.authorization, (/* @__PURE__ */ new Date()).toISOString());
-    const authorized = authCtx !== null && authCtx.keyId === conn.keyId && conn.mountPath !== void 0 && checkRegisterPath({
-      sk: {
-        scopes: authCtx.scopes,
-        id: authCtx.keyId,
-        ...authCtx.registerPaths !== void 0 ? { registerPaths: authCtx.registerPaths } : {}
-      },
-      targetPath: conn.mountPath,
-      action: "write",
-      existing: null
-    }).allow;
+    const authorized = conn.keyId !== void 0 && conn.mountPath !== void 0 && await reverifyDeviceAuthority({
+      store: this.store,
+      authorization: conn.authorization,
+      keyId: conn.keyId,
+      mountPath: conn.mountPath
+    });
     if (!authorized) {
       conn.session.reject(TBError.unauthenticated());
       return offline;
     }
     if (this.activeByDevice.get(deviceId) !== conn) return offline;
-    return await new Promise((resolve3) => conn.session.call(req, resolve3));
+    return await new Promise((resolve3) => conn.session.call(
+      req,
+      (result, disposition) => resolve3({ disposition, result })
+    ));
   }
   /** DeviceChannel.ws:Node 宿主的升级在 http 层处理,永不应命中此路由。 */
   async ws() {
@@ -40719,10 +41181,11 @@ var DeviceHub = class {
         }
         if (meta.disconnectedAt === void 0) {
           const now = (/* @__PURE__ */ new Date()).toISOString();
-          try {
-            await new NodeRegistryStore(this.store).setOnline(meta.mountPath, false, now);
-          } catch {
-          }
+          await markDeviceDisconnected({
+            mountPath: meta.mountPath,
+            now,
+            registry: new NodeRegistryStore(this.store)
+          });
           await this.store.put(KEY_DEVICE_META + meta.deviceId, { ...meta, disconnectedAt: now });
           this.scheduleReclaim(meta.deviceId, this.reclaimSec * 1e3);
         } else {
@@ -40820,9 +41283,7 @@ var DeviceHub = class {
       ...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.`
-      );
+      console.warn(deviceSearchCapacityWarning(conn.deviceId, mountPath));
     }
     const meta = { deviceId: conn.deviceId, mountPath, keyId, connectedAt: now };
     await this.store.put(KEY_DEVICE_META + conn.deviceId, meta);
@@ -40847,10 +41308,11 @@ var DeviceHub = class {
     const raw = await this.store.get(KEY_DEVICE_META + conn.deviceId);
     if (!isDeviceMeta(raw)) return;
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    try {
-      await new NodeRegistryStore(this.store).setOnline(raw.mountPath, false, now);
-    } catch {
-    }
+    await markDeviceDisconnected({
+      mountPath: raw.mountPath,
+      now,
+      registry: new NodeRegistryStore(this.store)
+    });
     await this.store.put(KEY_DEVICE_META + conn.deviceId, { ...raw, disconnectedAt: now });
     this.scheduleReclaim(conn.deviceId, this.reclaimSec * 1e3);
   }
@@ -40883,13 +41345,12 @@ var DeviceHub = class {
     }
     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);
-    const marker = await searchSync?.markSubtree(raw.mountPath);
-    try {
-      await new NodeRegistryStore(this.store).deleteSubtree(raw.mountPath);
-    } catch {
-    }
-    await searchSync?.removeSubtreeQuietly(raw.mountPath, marker);
+    await reclaimDeviceSubtree({
+      mountPath: raw.mountPath,
+      registry: new NodeRegistryStore(this.store),
+      ...this.search === void 0 ? {} : { search: this.search },
+      state: this.store
+    });
     await this.store.delete(KEY_DEVICE_META + deviceId);
   }
   /** ws 协议层探活:上一轮未回 pong → terminate(触发 close → markDisconnected)。 */
@@ -40973,7 +41434,13 @@ var DeviceRouter = class _DeviceRouter {
     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() });
+        resolve3({
+          disposition: "unknown",
+          result: {
+            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 });
@@ -40983,8 +41450,11 @@ var DeviceRouter = class _DeviceRouter {
         this.pending.delete(correlationId);
         clearTimeout(waiter.timer);
         waiter.resolve({
-          ok: false,
-          error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+          disposition: "unknown",
+          result: {
+            ok: false,
+            error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+          }
         });
       });
     });
@@ -40994,7 +41464,13 @@ var DeviceRouter = class _DeviceRouter {
     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() });
+      waiter.resolve({
+        disposition: "unknown",
+        result: {
+          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)));
@@ -41023,7 +41499,13 @@ var DeviceRouter = class _DeviceRouter {
     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() };
+      result = {
+        disposition: "unknown",
+        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(() => {
@@ -41330,6 +41812,7 @@ var commandSchema = external_exports.strictObject({
   argv: external_exports.array(external_exports.union([external_exports.string(), argumentSchema])).optional(),
   cwd: external_exports.string().min(1).optional(),
   effect: external_exports.enum(["read", "write", "destructive"]),
+  delivery: external_exports.enum(["realtime", "mailbox", "both"]).optional(),
   confirm: external_exports.boolean().optional(),
   timeoutMs: external_exports.number().int().positive().max(SHELL_EXEC_DEFAULT_TIMEOUT_MS).optional(),
   maxOutputBytes: external_exports.number().int().positive().max(STRUCTURED_COMMAND_MAX_OUTPUT_BYTES).optional(),
@@ -41958,7 +42441,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.19.0",
+  version: "0.21.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",
@@ -42297,26 +42780,27 @@ function createTbServer(config) {
   }
   const app = createTbApp(deps);
   let server;
-  let storeCleanupTimer;
-  let storeCleanupInFlight = false;
-  const runStoreCleanup = async () => {
-    if (storeCleanupInFlight) return;
-    storeCleanupInFlight = true;
+  let maintenanceTimer;
+  let maintenanceInFlight = false;
+  const runMaintenance = async () => {
+    if (maintenanceInFlight) return;
+    maintenanceInFlight = true;
     try {
       await cleanupDefaultStore(deps);
+      if (deps.encryptionKey !== void 0) await cleanupDeviceMailbox(deps);
     } finally {
-      storeCleanupInFlight = false;
+      maintenanceInFlight = false;
     }
   };
   const reportStoreCleanupFailure = () => {
     console.warn(JSON.stringify({ event: "tool_bridge_store_cleanup_failed" }));
   };
   const scheduleStoreCleanup = () => {
-    void runStoreCleanup().catch(reportStoreCleanupFailure);
-    storeCleanupTimer = setInterval(() => {
-      void runStoreCleanup().catch(reportStoreCleanupFailure);
+    void runMaintenance().catch(reportStoreCleanupFailure);
+    maintenanceTimer = setInterval(() => {
+      void runMaintenance().catch(reportStoreCleanupFailure);
     }, config.storeCleanupIntervalSec * 1e3);
-    storeCleanupTimer.unref?.();
+    maintenanceTimer.unref?.();
   };
   return {
     app,
@@ -42345,9 +42829,9 @@ function createTbServer(config) {
     },
     async close() {
       draining = true;
-      if (storeCleanupTimer !== void 0) {
-        clearInterval(storeCleanupTimer);
-        storeCleanupTimer = void 0;
+      if (maintenanceTimer !== void 0) {
+        clearInterval(maintenanceTimer);
+        maintenanceTimer = void 0;
       }
       let closed;
       if (server !== void 0) {