@tool-bridge/server 0.20.0 → 0.21.0

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

@@ -1,6 +1,6 @@
 import {
   createGuardedFetch
-} from "./chunk-3WL6EXYX.js";
+} from "./chunk-ZTTN6AJG.js";
 import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
@@ -55,6 +55,7 @@ import {
   any,
   appendVia,
   array,
+  assertNoCollision,
   assertPluginPayloadSize,
   assertPresignTtlSec,
   assertSecretRefUse,
@@ -196,7 +197,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-WIGQCP6O.js";
+} from "./chunk-MZCIPUNQ.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -821,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 function runCursorCleanup(opts) {
+  const { state } = opts;
+  if (state.compareAndSwap === void 0) {
+    throw new TBError("unavailable", "cursor cleanup requires StateStore.compareAndSwap");
   }
-  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]);
+  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) {
@@ -1173,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 = "";
@@ -1512,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 } };
 }
 
@@ -19809,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);
 }
@@ -19885,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) {
@@ -19929,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
   );
@@ -19938,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 }
     })
@@ -19951,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
   });
@@ -19981,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 })
       }
     });
   }
@@ -20130,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;
@@ -20149,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);
@@ -20170,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;
@@ -20323,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);
@@ -20402,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;
@@ -20420,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;
@@ -20429,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;
@@ -20522,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)) {
@@ -20561,6 +20557,7 @@ function customNodeInput(mountPath, deviceId, raw) {
   return input;
 }
 function nodesForHello(mountPath, deviceId, expose) {
+  const rawTargets = [mountPath];
   const nodes = [
     {
       path: mountPath,
@@ -20569,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",
@@ -20577,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",
@@ -20590,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}'`);
   }
@@ -20612,7 +20613,8 @@ async function assertRegisterPath(registry, ctx, targetPath) {
     },
     targetPath,
     action: "write",
-    existing
+    existing,
+    ...reservedRoots !== void 0 ? { reservedRoots } : {}
   });
   if (!res.allow) throw res.error;
 }
@@ -20633,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();
@@ -20662,15 +20664,43 @@ async function processDeviceHello(opts) {
   return { mountPath, keyId: authCtx.keyId, searchIndexed };
 }
 
-// ../app/src/deviceMailbox.ts
-var KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS = "sys:device-mailbox-cleanup-progress:v1";
-function positiveInt2(value, fallback, field) {
-  const actual = value ?? fallback;
-  if (!Number.isSafeInteger(actual) || actual < 1) {
-    throw new TBError("invalid_argument", `${field} must be a positive integer`);
+// ../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 {
   }
-  return actual;
 }
+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;
@@ -20684,39 +20714,27 @@ async function cleanupDeviceMailbox(deps, opts = {}) {
     throw new TBError("unavailable", "device mailbox cleanup requires StateStore.compareAndSwap");
   }
   const mailbox = createDeviceMailboxService(deps);
-  const maxPages = Math.min(positiveInt2(opts.maxPages, 8, "maxPages"), 64);
-  const limit = Math.min(positiveInt2(opts.limit, 200, "limit"), 200);
-  const raw = await deps.state.get(KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS);
-  let progress = raw === null ? null : parseProgress(raw);
-  let cursor = progress?.cursor;
+  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 };
-  for (let pageNumber = 0; pageNumber < maxPages; pageNumber++) {
-    const page = await mailbox.cleanup({ limit, ...cursor === void 0 ? {} : { cursor } });
-    aggregate.deleted += page.deleted;
-    aggregate.expired += page.expired;
-    aggregate.scanned += page.scanned;
-    if (page.cursor === void 0) {
-      if (progress !== null) {
-        await deps.state.compareAndSwap(
-          KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS,
-          progress.revision,
-          null
-        );
-      }
-      return aggregate;
-    }
-    const next = {
-      cursor: page.cursor,
-      revision: (progress?.revision ?? 0) + 1
-    };
-    if (!await deps.state.compareAndSwap(
-      KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS,
-      progress?.revision ?? null,
-      next
-    )) return aggregate;
-    progress = next;
-    cursor = next.cursor;
-  }
+  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 } };
 }
 
@@ -37320,6 +37338,99 @@ async function handleFeedbackDelete(c, env) {
   return feedbackJson(feedbackRemoveResponseSchema, { ok: true });
 }
 
+// ../app/src/responses.ts
+function tbErrorResponse(err) {
+  return new Response(JSON.stringify(tbErrorBodySchema.parse(err.toJSON())), {
+    status: err.httpStatus,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+function withSecurityHeaders(res) {
+  if (res.status === 101 || res.webSocket != null) return res;
+  const apply = (headers) => {
+    if (!headers.has("content-security-policy")) {
+      headers.set(
+        "content-security-policy",
+        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https: http:; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; object-src 'none'"
+      );
+    }
+    headers.set("x-content-type-options", "nosniff");
+    headers.set("x-frame-options", "DENY");
+    headers.set("referrer-policy", "no-referrer");
+  };
+  try {
+    apply(res.headers);
+    return res;
+  } catch {
+    const headers = new Headers(res.headers);
+    apply(headers);
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  }
+}
+async function runHandler(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isTBError(err)) return tbErrorResponse(err);
+    return tbErrorResponse(new TBError("internal", "internal error"));
+  }
+}
+function renderHelp(model, rep) {
+  if (rep === "json") {
+    return new Response(JSON.stringify(helpJsonSchema.parse(renderHelpJson(model))), {
+      headers: { "content-type": contentTypeFor("json") }
+    });
+  }
+  if (rep === "markdown") {
+    return new Response(renderHelpMarkdown(model), {
+      headers: { "content-type": contentTypeFor("markdown") }
+    });
+  }
+  return new Response(renderHelpDsl(model), {
+    headers: { "content-type": contentTypeFor("dsl") }
+  });
+}
+async function enrichHelp(model, path, store) {
+  try {
+    const [annotation, feedback] = await Promise.all([
+      new AnnotationStore(store).get(path),
+      path === "" ? Promise.resolve([]) : new FeedbackStore(store).helpItems(path)
+    ]);
+    return {
+      ...model,
+      ...annotation !== null ? { note: annotation.text } : {},
+      ...feedback.length > 0 ? { feedback } : {}
+    };
+  } catch {
+    return model;
+  }
+}
+function renderResult(value, rep) {
+  const json = JSON.stringify(value ?? null);
+  if (rep === "json") {
+    return new Response(json, { headers: { "content-type": contentTypeFor("json") } });
+  }
+  return new Response(`\`\`\`json
+${json}
+\`\`\`
+`, {
+    headers: { "content-type": contentTypeFor("markdown") }
+  });
+}
+function renderTreeDsl(tree) {
+  const lines = [];
+  const walk = (n, depth) => {
+    const indent = "  ".repeat(depth);
+    const label = n.path === "" ? "/" : n.path;
+    const trunc = n.truncated ? " \u2026" : "";
+    lines.push(`${indent}${label} [${n.kind}] ${n.description}${trunc}`);
+    for (const child of n.children ?? []) walk(child, depth + 1);
+  };
+  walk(tree, 0);
+  return `${lines.join("\n")}
+`;
+}
+
 // ../app/src/routes/deviceMailbox.ts
 var DEVICE_MAILBOX_IDEMPOTENCY_HEADER = "x-tb-idempotency-key";
 var DEVICE_MAILBOX_HTTP_BODY_BYTES = 272 * 1024;
@@ -37395,7 +37506,7 @@ function canManage(ctx, operation) {
 function assertCanManage(ctx, operation) {
   if (!canManage(ctx, operation)) throw TBError.notFound("device operation not found");
 }
-async function assertCurrentDeviceCredential(c, target) {
+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");
@@ -37414,7 +37525,8 @@ async function assertCurrentDeviceCredential(c, target) {
       scopes: ctx.scopes,
       ...ctx.registerPaths === void 0 ? {} : { registerPaths: ctx.registerPaths }
     },
-    targetPath: target.mountPath
+    targetPath: target.mountPath,
+    ...reservedRoots === void 0 ? {} : { reservedRoots }
   });
   if (!allowed.allow) throw allowed.error;
 }
@@ -37438,212 +37550,118 @@ async function enqueueDeviceCommand(c, env, input) {
   response.headers.set("x-tb-delivery", "mailbox");
   return response;
 }
-async function handleDeviceMailboxControl(c, env) {
-  const path = new URL(c.req.url).pathname.replace(/\/+$/, "");
-  const body = await mailboxJsonObject(c);
+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");
-  if (path === "/~device/operations/get") {
-    const input = parseBody(deviceOperationIdentityRequestSchema, body);
-    const result = await mailbox.get(input.deviceId, input.operationId);
-    assertCanManage(ctx, result);
-    return c.json(deviceOperationDetailSchema.parse(result));
-  }
-  if (path === "/~device/operations/list") {
-    const input = parseBody(deviceOperationListRequestSchema, body);
-    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) {
+  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 }));
     }
-    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");
-      }
+    if (cursor === previous) {
+      throw new TBError("internal", "device mailbox list cursor did not advance");
     }
-    return c.json(deviceOperationListResponseSchema.parse({ items }));
-  }
-  if (path === "/~device/operations/cancel") {
-    const input = parseBody(deviceOperationIdentityRequestSchema, body);
-    const current = await mailbox.get(input.deviceId, input.operationId);
-    assertCanManage(ctx, current);
-    return c.json(deviceOperationDetailSchema.parse(
-      await mailbox.cancel(input.deviceId, input.operationId)
-    ));
   }
-  throw TBError.notFound("no such path");
-}
-async function handleDeviceMailboxData(c, env) {
-  const path = new URL(c.req.url).pathname.replace(/\/+$/, "");
-  const body = await mailboxJsonObject(c);
-  const mailbox = env.mailbox();
-  const ctx = c.get("ctx");
-  const authorize = async (target) => await assertCurrentDeviceCredential(c, target);
-  if (path === "/~device/mailbox/claim") {
-    const input = parseBody(deviceOperationClaimRequestSchema, body);
-    return c.json(deviceOperationClaimResponseSchema.parse(await mailbox.claim({
-      ...input,
-      deviceKeyId: ctx.keyId,
-      authorize
-    })));
+  const resumeCursor = cursor;
+  if (resumeCursor === void 0) {
+    return c.json(deviceOperationListResponseSchema.parse({ items }));
   }
-  if (path === "/~device/mailbox/renew") {
-    const input = parseBody(deviceOperationRenewRequestSchema, body);
-    return c.json(deviceOperationRenewResponseSchema.parse(await mailbox.renew({
-      ...input,
-      deviceKeyId: ctx.keyId,
-      authorize
-    })));
-  }
-  if (path === "/~device/mailbox/complete") {
-    const input = parseBody(deviceOperationCompleteRequestSchema, body);
-    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 mailbox.complete({
+  let probeCursor = resumeCursor;
+  while (probeCursor !== void 0) {
+    const previous = probeCursor;
+    const page = await mailbox.list({
       deviceId: input.deviceId,
-      operationId: input.operationId,
-      leaseId: input.leaseId,
-      deviceKeyId: ctx.keyId,
-      authorize
-    }, completion)));
-  }
-  throw TBError.notFound("no such path");
-}
-
-// ../app/src/responses.ts
-function tbErrorResponse(err) {
-  return new Response(JSON.stringify(tbErrorBodySchema.parse(err.toJSON())), {
-    status: err.httpStatus,
-    headers: { "content-type": "application/json; charset=utf-8" }
-  });
-}
-function withSecurityHeaders(res) {
-  if (res.status === 101 || res.webSocket != null) return res;
-  const apply = (headers) => {
-    if (!headers.has("content-security-policy")) {
-      headers.set(
-        "content-security-policy",
-        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https: http:; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; object-src 'none'"
-      );
+      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");
     }
-    headers.set("x-content-type-options", "nosniff");
-    headers.set("x-frame-options", "DENY");
-    headers.set("referrer-policy", "no-referrer");
-  };
-  try {
-    apply(res.headers);
-    return res;
-  } catch {
-    const headers = new Headers(res.headers);
-    apply(headers);
-    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
   }
+  return c.json(deviceOperationListResponseSchema.parse({ items }));
 }
-async function runHandler(fn) {
-  try {
-    return await fn();
-  } catch (err) {
-    if (isTBError(err)) return tbErrorResponse(err);
-    return tbErrorResponse(new TBError("internal", "internal error"));
-  }
+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)
+  })));
 }
-function renderHelp(model, rep) {
-  if (rep === "json") {
-    return new Response(JSON.stringify(helpJsonSchema.parse(renderHelpJson(model))), {
-      headers: { "content-type": contentTypeFor("json") }
-    });
-  }
-  if (rep === "markdown") {
-    return new Response(renderHelpMarkdown(model), {
-      headers: { "content-type": contentTypeFor("markdown") }
-    });
-  }
-  return new Response(renderHelpDsl(model), {
-    headers: { "content-type": contentTypeFor("dsl") }
-  });
+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 enrichHelp(model, path, store) {
-  try {
-    const [annotation, feedback] = await Promise.all([
-      new AnnotationStore(store).get(path),
-      path === "" ? Promise.resolve([]) : new FeedbackStore(store).helpItems(path)
-    ]);
-    return {
-      ...model,
-      ...annotation !== null ? { note: annotation.text } : {},
-      ...feedback.length > 0 ? { feedback } : {}
+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 }
     };
-  } catch {
-    return model;
-  }
-}
-function renderResult(value, rep) {
-  const json = JSON.stringify(value ?? null);
-  if (rep === "json") {
-    return new Response(json, { headers: { "content-type": contentTypeFor("json") } });
-  }
-  return new Response(`\`\`\`json
-${json}
-\`\`\`
-`, {
-    headers: { "content-type": contentTypeFor("markdown") }
-  });
-}
-function renderTreeDsl(tree) {
-  const lines = [];
-  const walk = (n, depth) => {
-    const indent = "  ".repeat(depth);
-    const label = n.path === "" ? "/" : n.path;
-    const trunc = n.truncated ? " \u2026" : "";
-    lines.push(`${indent}${label} [${n.kind}] ${n.description}${trunc}`);
-    for (const child of n.children ?? []) walk(child, depth + 1);
-  };
-  walk(tree, 0);
-  return `${lines.join("\n")}
-`;
+  } 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
@@ -37867,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;
@@ -37923,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);
@@ -37943,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") }
   });
@@ -38045,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];
     }
@@ -38713,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;
@@ -38738,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;
@@ -38893,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";
@@ -39610,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 },
@@ -39925,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");
@@ -39941,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 }
@@ -40011,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,
@@ -40081,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;
@@ -40127,20 +40136,8 @@ var toolSpecCommand = (node, tool, providerBacked = false) => {
     ...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;
@@ -40159,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" },
@@ -40227,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(
@@ -40241,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 = [];
@@ -40311,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));
             }
           }
         }
@@ -40333,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;
@@ -40341,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) {
@@ -40444,7 +40426,7 @@ 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 result2 = await provider.call(upstreamName, args);
         return {
@@ -40606,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")));
@@ -40670,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(
@@ -40690,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") {
@@ -40712,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") {
@@ -40736,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")) {
@@ -40778,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) {
@@ -40841,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;
@@ -40862,7 +40832,7 @@ function createRouteEnv(deps) {
 
 // ../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");
@@ -40901,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");
@@ -40913,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);
 }
@@ -41021,6 +40993,7 @@ function createTbApp(deps) {
   });
   registerMcpRoute(app, env);
   registerSearchRoute(app, env);
+  registerDeviceMailboxRoutes(app, env);
   app.get(
     "/system/device/ws",
     (c) => runHandler(async () => {
@@ -41061,13 +41034,6 @@ function createTbApp(deps) {
     async (c) => await runHandler(async () => {
       const segs = new URL(c.req.url).pathname.replace(/\/+$/, "").split("/");
       const last = segs.pop() ?? "";
-      const pathname = new URL(c.req.url).pathname.replace(/\/+$/, "");
-      if (pathname.startsWith("/~device/operations/")) {
-        return await handleDeviceMailboxControl(c, env);
-      }
-      if (pathname.startsWith("/~device/mailbox/")) {
-        return await handleDeviceMailboxData(c, env);
-      }
       if (last === "~register") return await handleRegister(c, env);
       if (last === "~authorize") return await handleAuthorize(c, env);
       if (last === "~feedback" || segs[segs.length - 1] === "~feedback") {
@@ -41178,17 +41144,12 @@ var DeviceHub = class {
     };
     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;
@@ -41220,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 {
@@ -41321,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);
@@ -41348,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);
   }
@@ -41384,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)。 */
@@ -42481,7 +42441,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.20.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",