@tool-bridge/server 0.17.0 → 0.19.0

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

@@ -1,6 +1,6 @@
 import {
   createGuardedFetch
-} from "./chunk-U5UHT7CX.js";
+} from "./chunk-SWBNHIO4.js";
 import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
@@ -40,9 +40,11 @@ import {
   TB_ERROR_CODES,
   TOOL_SEARCH_AUDIT_NODE_LIMIT,
   TOOL_SEARCH_BATCH_LIMIT,
+  TOOL_SEARCH_DESCRIPTION_BYTES_MAX,
   TOOL_SEARCH_INSERT_SNAPSHOT_SQL,
   TOOL_SEARCH_INSERT_SQL,
   TOOL_SEARCH_PAGE_BYTES,
+  TOOL_SEARCH_RANKING_VERSION,
   TOOL_SEARCH_SCHEMA_STATEMENTS,
   TOOL_SEARCH_WORK_LIMIT,
   ZodIssueCode,
@@ -124,6 +126,7 @@ import {
   normalizeEntryPath,
   normalizePath,
   normalizeToolSearchLimit,
+  normalizeToolSearchOptions,
   normalizeToolSearchPath,
   normalizeUpstreamError,
   number,
@@ -146,6 +149,7 @@ import {
   pgSearchDialect,
   pluginTokenSecretName,
   prefixUpperBound,
+  prepareToolSearchQuery,
   preprocess,
   readinessResponseSchema,
   record,
@@ -169,8 +173,11 @@ import {
   toJSONSchema,
   toolHelpModel,
   toolSearchPageSchema,
+  toolSearchRelevanceSchema,
   toolSearchRequestSchema,
   toolSearchSnapshotDigest,
+  toolSearchSourceResultSchema,
+  toolSearchSourceSchema,
   toolsToHelpModel,
   treeJsonSchema,
   union,
@@ -178,7 +185,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-RVWZN3CI.js";
+} from "./chunk-OKRZPQ3R.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -10023,13 +10030,13 @@ var require_utils = /* @__PURE__ */ __commonJSMin(((exports, module) => {
     const buffer = [];
     let endipv6Encountered = false;
     let endIpv6 = false;
-    let consume = consumeHextets;
+    let consume2 = consumeHextets;
     for (let i = 0; i < input.length; i++) {
       const cursor = input[i];
       if (cursor === "[" || cursor === "]") continue;
       if (cursor === ":") {
         if (endipv6Encountered === true) endIpv6 = true;
-        if (!consume(buffer, address, output)) break;
+        if (!consume2(buffer, address, output)) break;
         if (++tokenCount > 7) {
           output.error = true;
           break;
@@ -10038,14 +10045,14 @@ var require_utils = /* @__PURE__ */ __commonJSMin(((exports, module) => {
         address.push(":");
         continue;
       } else if (cursor === "%") {
-        if (!consume(buffer, address, output)) break;
-        consume = consumeIsZone;
+        if (!consume2(buffer, address, output)) break;
+        consume2 = consumeIsZone;
       } else {
         buffer.push(cursor);
         continue;
       }
     }
-    if (buffer.length) if (consume === consumeIsZone) output.zone = buffer.join("");
+    if (buffer.length) if (consume2 === consumeIsZone) output.zone = buffer.join("");
     else if (endIpv6) address.push(buffer.join(""));
     else address.push(stringArrayToHexStripped(buffer));
     output.address = address.join("");
@@ -19188,12 +19195,51 @@ async function invalidateMcpOAuth(store, nodePath) {
   await store.delete(KEY_OAUTH_TOKENS + nodePath);
   await store.delete(KEY_OAUTH_DISCOVERY + nodePath);
 }
+async function assertMcpOAuthConfig(config, secrets) {
+  if (config === null || typeof config !== "object") return;
+  const candidate = config;
+  if (candidate.kind !== "mcp" || candidate.oauthClient === void 0) return;
+  if (candidate.auth !== "oauth") {
+    throw new TBError("invalid_argument", "mcp oauthClient \u53EA\u80FD\u4E0E auth:'oauth' \u4E00\u8D77\u4F7F\u7528");
+  }
+  if (candidate.oauthClient === null || typeof candidate.oauthClient !== "object") {
+    throw new TBError("invalid_argument", "mcp oauthClient \u5FC5\u987B\u662F\u5BF9\u8C61");
+  }
+  const client = candidate.oauthClient;
+  const unknown2 = Object.keys(client).filter((key) => !["clientId", "clientSecretRef"].includes(key));
+  if (unknown2.length > 0) {
+    throw new TBError(
+      "invalid_argument",
+      `mcp oauthClient \u4E0D\u63A5\u53D7\u5B57\u6BB5:${unknown2.join(", ")};client secret \u5FC5\u987B\u8D70 clientSecretRef`
+    );
+  }
+  if (typeof client.clientId !== "string" || client.clientId.trim() === "") {
+    throw new TBError("invalid_argument", "mcp oauthClient.clientId \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (client.clientSecretRef === void 0) return;
+  if (typeof client.clientSecretRef !== "string" || client.clientSecretRef.trim() === "") {
+    throw new TBError("invalid_argument", "mcp oauthClient.clientSecretRef \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (await secrets.resolve(client.clientSecretRef) === void 0) {
+    throw new TBError(
+      "invalid_argument",
+      `OAuth client secret ref '${client.clientSecretRef}' \u4E0D\u5B58\u5728\u6216\u65E0\u6CD5\u89E3\u5BC6`
+    );
+  }
+}
 function reauthorizeRequired(nodePath) {
   return new TBError(
     "permission_denied",
     `mcp upstream '${nodePath}' requires (re)authorization: run \`tb tool auth ${nodePath}\``
   );
 }
+var mcpOAuthFetch = (input, init) => {
+  const headers = new Headers(
+    init?.headers ?? (input instanceof Request ? input.headers : void 0)
+  );
+  const tokenRequest = headers.get("content-type")?.toLowerCase().startsWith("application/x-www-form-urlencoded") === true;
+  return fetch(input, tokenRequest ? { ...init, redirect: "error" } : init);
+};
 async function stateCryptoKey(secret) {
   const digest = await crypto.subtle.digest(
     "SHA-256",
@@ -19225,7 +19271,7 @@ async function openOAuthState(state, secret) {
       ciphertext
     );
     const payload = JSON.parse(new TextDecoder().decode(plain));
-    if (typeof payload.p !== "string" || typeof payload.v !== "string" || typeof payload.exp !== "number" || payload.r !== void 0 && typeof payload.r !== "string") {
+    if (typeof payload.p !== "string" || typeof payload.v !== "string" || typeof payload.exp !== "number" || payload.r !== void 0 && typeof payload.r !== "string" || payload.o !== void 0 && (typeof payload.o !== "object" || payload.o === null || typeof payload.o.i !== "string" || payload.o.r !== void 0 && typeof payload.o.r !== "string")) {
       return null;
     }
     return payload;
@@ -19252,11 +19298,31 @@ var GatewayMcpOAuthProvider = class {
       redirect_uris: [this.redirectUrl],
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
-      token_endpoint_auth_method: "none"
-      // public client,PKCE 保护
+      // DCR 与 static public client 都是 PKCE public client；confidential client 由 AS
+      // metadata + client_secret 自动协商 basic/post，不在 metadata 里误声明 none。
+      ...this.opts.oauthClient?.clientSecretRef === void 0 ? { token_endpoint_auth_method: "none" } : {}
     };
   }
-  async clientInformation() {
+  async clientInformation(ctx) {
+    const configured = this.opts.oauthClient;
+    if (configured !== void 0) {
+      let clientSecret;
+      if (configured.clientSecretRef !== void 0) {
+        clientSecret = await this.opts.secrets.resolve(configured.clientSecretRef);
+        if (clientSecret === void 0) {
+          throw new TBError(
+            "unavailable",
+            `OAuth client secret ref '${configured.clientSecretRef}' \u4E0D\u5B58\u5728\u6216\u65E0\u6CD5\u89E3\u5BC6`,
+            { retryable: false }
+          );
+        }
+      }
+      return {
+        client_id: configured.clientId,
+        ...clientSecret !== void 0 ? { client_secret: clientSecret } : {},
+        ...ctx?.issuer !== void 0 ? { issuer: ctx.issuer } : {}
+      };
+    }
     const raw = await this.opts.store.get(KEY_OAUTH_CLIENT + this.opts.nodePath);
     if (raw === null) {
       if (this.opts.mode === "deny") throw reauthorizeRequired(this.opts.nodePath);
@@ -19265,14 +19331,47 @@ var GatewayMcpOAuthProvider = class {
     return raw;
   }
   async saveClientInformation(info) {
+    if (this.opts.oauthClient !== void 0) return;
     await this.opts.store.put(KEY_OAUTH_CLIENT + this.opts.nodePath, info);
   }
-  async tokens() {
+  async tokens(ctx) {
     const raw = await this.opts.store.get(KEY_OAUTH_TOKENS + this.opts.nodePath);
-    return raw === null ? void 0 : raw;
+    if (raw === null) return void 0;
+    const tokens = raw;
+    const discovery = await this.opts.store.get(KEY_OAUTH_DISCOVERY + this.opts.nodePath);
+    const discoveredIssuer = discovery?.authorizationServerMetadata?.issuer;
+    if (discoveredIssuer !== void 0 && tokens.issuer !== void 0 && tokens.issuer !== discoveredIssuer) {
+      await this.opts.store.delete(KEY_OAUTH_TOKENS + this.opts.nodePath);
+      return void 0;
+    }
+    let binding = tokens.toolBridgeBinding;
+    const client = await this.clientInformation(ctx);
+    if (binding === void 0 && this.opts.oauthClient === void 0 && client !== void 0 && "redirect_uris" in client && client.redirect_uris?.length === 1) {
+      binding = { clientId: client.client_id, redirectUri: client.redirect_uris[0] };
+      await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, {
+        ...tokens,
+        toolBridgeBinding: binding
+      });
+    }
+    const bindingMismatch = binding === void 0 || client === void 0 || binding.clientId !== client.client_id || this.opts.mode === "interactive" && binding.redirectUri !== this.redirectUrl;
+    if (bindingMismatch) {
+      await this.opts.store.delete(KEY_OAUTH_TOKENS + this.opts.nodePath);
+      return void 0;
+    }
+    return tokens;
   }
-  async saveTokens(tokens) {
-    await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, tokens);
+  async saveTokens(tokens, ctx) {
+    const client = await this.clientInformation(ctx);
+    if (client === void 0) throw new TBError("internal", "OAuth client information missing");
+    const previous = await this.opts.store.get(KEY_OAUTH_TOKENS + this.opts.nodePath);
+    const redirectUri = this.opts.mode === "interactive" ? this.redirectUrl : previous?.toolBridgeBinding?.redirectUri ?? ("redirect_uris" in client && client.redirect_uris?.length === 1 ? client.redirect_uris[0] : void 0);
+    if (redirectUri === void 0) {
+      throw new TBError("permission_denied", "OAuth grant redirect binding missing; reauthorize");
+    }
+    await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, {
+      ...tokens,
+      toolBridgeBinding: { clientId: client.client_id, redirectUri }
+    });
   }
   async saveCodeVerifier(codeVerifier) {
     this.verifier = codeVerifier;
@@ -19294,7 +19393,13 @@ var GatewayMcpOAuthProvider = class {
         p: this.opts.nodePath,
         v: this.codeVerifier(),
         exp: Math.floor(Date.now() / 1e3) + STATE_TTL_SEC,
-        ...this.opts.redirectUri !== void 0 ? { r: this.opts.redirectUri } : {}
+        r: this.redirectUrl,
+        ...this.opts.oauthClient !== void 0 ? {
+          o: {
+            i: this.opts.oauthClient.clientId,
+            ...this.opts.oauthClient.clientSecretRef !== void 0 ? { r: this.opts.oauthClient.clientSecretRef } : {}
+          }
+        } : {}
       },
       this.opts.encryptionKey
     );
@@ -19311,7 +19416,9 @@ var GatewayMcpOAuthProvider = class {
   /** SDK 对 InvalidClient/InvalidGrant 等可恢复错误的重试钩子:清对应缓存后重走。 */
   async invalidateCredentials(scope) {
     const { store, nodePath } = this.opts;
-    if (scope === "all" || scope === "client") await store.delete(KEY_OAUTH_CLIENT + nodePath);
+    if ((scope === "all" || scope === "client") && this.opts.oauthClient === void 0) {
+      await store.delete(KEY_OAUTH_CLIENT + nodePath);
+    }
     if (scope === "all" || scope === "tokens") await store.delete(KEY_OAUTH_TOKENS + nodePath);
     if (scope === "all" || scope === "discovery") await store.delete(KEY_OAUTH_DISCOVERY + nodePath);
     if (scope === "all" || scope === "verifier") this.verifier = void 0;
@@ -19338,6 +19445,13 @@ async function guardOAuth(fn) {
     return await fn();
   } catch (err) {
     if (err instanceof TBError) throw err;
+    if (err instanceof Error && /does not support dynamic client registration/i.test(err.message)) {
+      throw new TBError(
+        "invalid_argument",
+        "authorization server \u672A\u63D0\u4F9B\u52A8\u6001\u5BA2\u6237\u7AEF\u6CE8\u518C\uFF1B\u8BF7\u914D\u7F6E\u9884\u6CE8\u518C OAuth client(CLI: --oauth-client-id\uFF0C\u53EF\u9009 --oauth-client-secret-ref)",
+        { retryable: false }
+      );
+    }
     throw new TBError(
       "unavailable",
       `OAuth flow failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -19346,11 +19460,13 @@ async function guardOAuth(fn) {
   }
 }
 async function startMcpAuthorization(opts) {
-  if (opts.redirectUri !== void 0) {
-    assertLocalRedirectUri(opts.redirectUri);
+  if (opts.redirectUri !== void 0) assertLocalRedirectUri(opts.redirectUri);
+  const redirectUri = opts.redirectUri ?? `${opts.origin}${OAUTH_CALLBACK_PATH}`;
+  if (opts.oauthClient === void 0) {
     const cached = await opts.store.get(KEY_OAUTH_CLIENT + opts.nodePath);
-    if (cached !== null && !(cached.redirect_uris ?? []).includes(opts.redirectUri)) {
+    if (cached !== null && !(cached.redirect_uris ?? []).includes(redirectUri)) {
       await opts.store.delete(KEY_OAUTH_CLIENT + opts.nodePath);
+      await opts.store.delete(KEY_OAUTH_TOKENS + opts.nodePath);
     }
   }
   const provider = new GatewayMcpOAuthProvider({
@@ -19359,10 +19475,12 @@ async function startMcpAuthorization(opts) {
     encryptionKey: opts.encryptionKey,
     mode: "interactive",
     origin: opts.origin,
+    secrets: opts.secrets,
+    ...opts.oauthClient !== void 0 ? { oauthClient: opts.oauthClient } : {},
     ...opts.redirectUri !== void 0 ? { redirectUri: opts.redirectUri } : {}
   });
   return await guardOAuth(async () => {
-    const result = await auth(provider, { serverUrl: opts.serverUrl });
+    const result = await auth(provider, { serverUrl: opts.serverUrl, fetchFn: mcpOAuthFetch });
     if (result === "AUTHORIZED") return { status: "authorized" };
     const url2 = provider.capturedAuthorizationUrl;
     if (url2 === void 0) {
@@ -19378,13 +19496,17 @@ async function finishMcpAuthorization(opts) {
     encryptionKey: opts.encryptionKey,
     mode: "interactive",
     origin: opts.origin,
+    secrets: opts.secrets,
+    ...opts.oauthClient !== void 0 ? { oauthClient: opts.oauthClient } : {},
     ...opts.redirectUri !== void 0 ? { redirectUri: opts.redirectUri } : {}
   });
   provider.setCodeVerifier(opts.codeVerifier);
   await guardOAuth(async () => {
     const result = await auth(provider, {
       serverUrl: opts.serverUrl,
-      authorizationCode: opts.code
+      authorizationCode: opts.code,
+      fetchFn: mcpOAuthFetch,
+      ...opts.authorizationResponseIssuer !== void 0 ? { iss: opts.authorizationResponseIssuer } : {}
     });
     if (result !== "AUTHORIZED") {
       throw new TBError("internal", "authorization did not complete");
@@ -19451,7 +19573,7 @@ var noStandaloneSseFetch = (input, init) => {
   if (String(method).toUpperCase() === "GET" && accept.includes("text/event-stream")) {
     return Promise.resolve(new Response(null, { status: 405, statusText: "Method Not Allowed" }));
   }
-  return fetch(input, init);
+  return mcpOAuthFetch(input, init);
 };
 var ERA_KEY_PREFIX = "mcpera:";
 var LEGACY_ERA_HORIZON_SEC = 300;
@@ -19591,7 +19713,9 @@ function createMcpProvider(config, secrets, opts) {
           store: opts.oauth.store,
           nodePath,
           encryptionKey: opts.oauth.encryptionKey,
-          mode: "deny"
+          mode: "deny",
+          secrets,
+          ...config.oauthClient !== void 0 ? { oauthClient: config.oauthClient } : {}
         })
       };
     }
@@ -28157,13 +28281,13 @@ var require_utils2 = /* @__PURE__ */ __commonJSMin2(((exports, module) => {
     const buffer = [];
     let endipv6Encountered = false;
     let endIpv6 = false;
-    let consume = consumeHextets;
+    let consume2 = consumeHextets;
     for (let i = 0; i < input.length; i++) {
       const cursor = input[i];
       if (cursor === "[" || cursor === "]") continue;
       if (cursor === ":") {
         if (endipv6Encountered === true) endIpv6 = true;
-        if (!consume(buffer, address, output)) break;
+        if (!consume2(buffer, address, output)) break;
         if (++tokenCount > 7) {
           output.error = true;
           break;
@@ -28172,14 +28296,14 @@ var require_utils2 = /* @__PURE__ */ __commonJSMin2(((exports, module) => {
         address.push(":");
         continue;
       } else if (cursor === "%") {
-        if (!consume(buffer, address, output)) break;
-        consume = consumeIsZone;
+        if (!consume2(buffer, address, output)) break;
+        consume2 = consumeIsZone;
       } else {
         buffer.push(cursor);
         continue;
       }
     }
-    if (buffer.length) if (consume === consumeIsZone) output.zone = buffer.join("");
+    if (buffer.length) if (consume2 === consumeIsZone) output.zone = buffer.join("");
     else if (endIpv6) address.push(buffer.join(""));
     else address.push(stringArrayToHexStripped(buffer));
     output.address = address.join("");
@@ -36350,6 +36474,121 @@ function createPluginContextProvider(opts) {
 
 // ../app/src/providers/remote.ts
 var VIA_HEADER = "x-tb-via";
+function remoteAbortError() {
+  return new TBError("unavailable", "remote request aborted", { retryable: true });
+}
+function remoteResponseTooLarge(maxBytes) {
+  return new TBError(
+    "unavailable",
+    `remote response body exceeds ${maxBytes} bytes`,
+    { retryable: false }
+  );
+}
+function isAbortError(error, signal) {
+  return signal?.aborted === true || error instanceof Error && error.name === "AbortError";
+}
+function signalAborted(signal) {
+  return signal?.aborted === true;
+}
+function declaredContentLength(response) {
+  const value = response.headers.get("content-length");
+  if (value === null || !/^\d+$/.test(value)) return void 0;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+async function readRemoteResponseBody(response, maxBytes, signal) {
+  if (signal?.aborted === true) throw remoteAbortError();
+  const declared = declaredContentLength(response);
+  if (maxBytes !== void 0 && declared !== void 0 && declared > maxBytes) {
+    void response.body?.cancel().catch(() => {
+    });
+    throw remoteResponseTooLarge(maxBytes);
+  }
+  if (response.body === null) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  let abortListener;
+  const abortPromise = signal === void 0 ? void 0 : new Promise((_resolve, reject) => {
+    abortListener = () => {
+      reject(remoteAbortError());
+      void reader.cancel().catch(() => {
+      });
+    };
+    signal.addEventListener("abort", abortListener, { once: true });
+    if (signal.aborted) abortListener();
+  });
+  try {
+    while (true) {
+      const result = await (abortPromise === void 0 ? reader.read() : Promise.race([reader.read(), abortPromise]));
+      if (signalAborted(signal)) throw remoteAbortError();
+      if (result.done) break;
+      total += result.value.byteLength;
+      if (maxBytes !== void 0 && total > maxBytes) {
+        void reader.cancel().catch(() => {
+        });
+        throw remoteResponseTooLarge(maxBytes);
+      }
+      chunks.push(result.value);
+    }
+  } catch (error) {
+    if (error instanceof TBError) throw error;
+    if (isAbortError(error, signal)) throw remoteAbortError();
+    throw normalizeUpstreamError({
+      kind: "network",
+      message: "failed to read remote response body"
+    });
+  } finally {
+    if (abortListener !== void 0) signal?.removeEventListener("abort", abortListener);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+var DEFAULT_FEDERATED_SEARCH_SETTINGS = {
+  maxConcurrency: 4,
+  maxResponseBodyBytes: 512 * 1024,
+  maxSources: 16,
+  minChildWorkMs: 200,
+  perHopReturnReserveMs: 100,
+  sessionTtlMs: 5 * 60 * 1e3,
+  totalDeadlineMs: 2500
+};
+function federatedSearchSettings(settings) {
+  const configured = settings.federatedSearch ?? {};
+  const positive = (value, fallback) => value !== void 0 && Number.isFinite(value) && Number.isInteger(value) && value > 0 ? value : fallback;
+  return {
+    maxConcurrency: positive(
+      configured.maxConcurrency,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.maxConcurrency
+    ),
+    maxResponseBodyBytes: positive(
+      configured.maxResponseBodyBytes,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.maxResponseBodyBytes
+    ),
+    maxSources: positive(configured.maxSources, DEFAULT_FEDERATED_SEARCH_SETTINGS.maxSources),
+    minChildWorkMs: positive(
+      configured.minChildWorkMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.minChildWorkMs
+    ),
+    perHopReturnReserveMs: positive(
+      configured.perHopReturnReserveMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.perHopReturnReserveMs
+    ),
+    sessionTtlMs: positive(
+      configured.sessionTtlMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.sessionTtlMs
+    ),
+    totalDeadlineMs: positive(
+      configured.totalDeadlineMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.totalDeadlineMs
+    )
+  };
+}
 function selfInstanceId(settings, requestUrl) {
   if (settings.instanceId !== void 0 && settings.instanceId.length > 0) {
     return settings.instanceId;
@@ -36368,6 +36607,13 @@ function assertRemoteAllowed(baseUrl, settings) {
   }
 }
 async function passthroughRemote(opts) {
+  if (opts.maxResponseBodyBytes !== void 0 && (!Number.isSafeInteger(opts.maxResponseBodyBytes) || opts.maxResponseBodyBytes < 0)) {
+    throw new TBError(
+      "invalid_argument",
+      "maxResponseBodyBytes must be a non-negative safe integer"
+    );
+  }
+  if (opts.signal?.aborted === true) throw remoteAbortError();
   const secErr = assertSecureUrl(opts.config.baseUrl, opts.settings.allowInsecure);
   if (secErr) throw secErr;
   if (!checkAllowlist(opts.config.baseUrl, opts.settings.allowlist)) {
@@ -36392,6 +36638,16 @@ async function passthroughRemote(opts) {
   if (accept !== null) outHeaders.accept = accept;
   const contentType = opts.headers.get("content-type");
   if (contentType !== null) outHeaders["content-type"] = contentType;
+  for (const name of [
+    "x-tb-search-remaining-ms",
+    "x-tb-search-session-ttl-ms",
+    "x-tb-search-source-budget",
+    "x-tb-search-validate-snapshot",
+    "x-tb-search-want-snapshot"
+  ]) {
+    const value = opts.headers.get(name);
+    if (value !== null) outHeaders[name] = value;
+  }
   if (opts.config.skRef !== void 0) {
     const cred = await opts.secrets.resolve(opts.config.skRef);
     if (cred === void 0) {
@@ -36419,17 +36675,29 @@ async function passthroughRemote(opts) {
     resp = await fetch(target, {
       method: opts.method,
       headers: outHeaders,
+      // remote 请求可能携带高权 service credential 与敏感 arguments。禁止自动跟随任何
+      // 30x，避免 redirect 绕过初始 baseUrl 的 allowlist/HTTPS 校验或把 body 发往另一目标。
+      redirect: "error",
+      ...opts.signal === void 0 ? {} : { signal: opts.signal },
       ...opts.body !== void 0 && opts.body.length > 0 ? { body: opts.body } : {}
     });
   } catch (err) {
+    if (isAbortError(err, opts.signal)) throw remoteAbortError();
     throw normalizeUpstreamError({
       kind: "network",
       message: err instanceof Error ? err.message : String(err)
     });
   }
-  const respBody = await resp.text();
+  const respBody = await readRemoteResponseBody(
+    resp,
+    opts.maxResponseBodyBytes,
+    opts.signal
+  );
   const respCt = resp.headers.get("content-type") ?? "application/octet-stream";
-  return new Response(respBody, { status: resp.status, headers: { "content-type": respCt } });
+  return new Response(respBody.buffer, {
+    status: resp.status,
+    headers: { "content-type": respCt }
+  });
 }
 
 // ../app/src/tbApp.ts
@@ -36454,8 +36722,11 @@ var schemas = {
   OAuthAuthorizeResponse: oauthAuthorizeResponseSchema,
   Readiness: readinessResponseSchema,
   RegistryNode: registryNodeSchema,
+  SearchRelevance: toolSearchRelevanceSchema,
   SearchRequest: toolSearchRequestSchema,
   SearchResponse: toolSearchPageSchema,
+  SearchSource: toolSearchSourceSchema,
+  SearchSourceResult: toolSearchSourceResultSchema,
   Tree: treeJsonSchema
 };
 for (const [id, schema] of Object.entries(schemas)) schemaRegistry.add(schema, { id });
@@ -36980,6 +37251,7 @@ function renderTreeDsl(tree) {
 }
 
 // ../app/src/federation.ts
+var SEARCH_REMAINING_MS_HEADER = "x-tb-search-remaining-ms";
 function remoteProtocolError(message) {
   return new TBError("unavailable", message, { retryable: false });
 }
@@ -36987,28 +37259,26 @@ function canonicalRemotePath(path, allowRoot) {
   if (path !== path.replace(/^\/+|\/+$/g, "")) {
     throw remoteProtocolError(`remote returned non-canonical path '${path}'`);
   }
+  if (path !== path.toLowerCase()) {
+    throw remoteProtocolError(`remote returned non-canonical path '${path}'`);
+  }
   const invalid = validatePath(path, { allowRoot });
   if (invalid !== null) throw remoteProtocolError(`remote returned invalid path '${path}'`);
   for (const segment of path === "" ? [] : path.split("/")) {
-    let decoded = segment;
-    for (let pass = 0; pass < 4; pass++) {
-      if (decoded === "." || decoded === ".." || decoded.startsWith("~") || decoded.includes("/") || decoded.includes("\\") || [...decoded].some((char) => {
-        const code = char.charCodeAt(0);
-        return code <= 31 || code === 127;
-      })) {
-        throw remoteProtocolError(`remote returned unsafe path segment '${segment}'`);
-      }
-      let next;
-      try {
-        next = decodeURIComponent(decoded);
-      } catch {
-        throw remoteProtocolError(`remote returned malformed encoded path '${path}'`);
-      }
-      if (next === decoded) break;
-      if (pass === 3) {
-        throw remoteProtocolError(`remote returned over-encoded path '${path}'`);
-      }
-      decoded = next;
+    if (segment === "." || segment === ".." || segment.startsWith("~") || segment.includes("\\") || segment.includes("?") || segment.includes("#") || [...segment].some((char) => {
+      const code = char.charCodeAt(0);
+      return code <= 31 || code === 127;
+    })) {
+      throw remoteProtocolError(`remote returned unsafe path segment '${segment}'`);
+    }
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      throw remoteProtocolError(`remote returned malformed encoded path '${path}'`);
+    }
+    if (decoded !== segment) {
+      throw remoteProtocolError(`remote returned non-canonical encoded path '${path}'`);
     }
   }
   return path;
@@ -37016,19 +37286,104 @@ function canonicalRemotePath(path, allowRoot) {
 function remotePathWithin(nodePath, commandPath) {
   return nodePath === "" || commandPath === nodePath || commandPath.startsWith(`${nodePath}/`);
 }
-function localizeRemoteEntry(mountPath, remoteParentPath, entry) {
-  const rel = canonicalRemotePath(entry.path, false);
-  const parent = rel.split("/").slice(0, -1).join("/");
-  if (parent !== remoteParentPath) {
-    throw remoteProtocolError(`remote ~tree child '${rel}' is not a direct descendant`);
+var CALLABLE_TREE_KINDS = /* @__PURE__ */ new Set(["device", "http", "mcp", "remote", "tool"]);
+function visibleRemotePath(ctx, path, kind) {
+  if (!check(ctx, path, "read").allow) return false;
+  return !CALLABLE_TREE_KINDS.has(kind) || check(ctx, path, "call").allow;
+}
+var RemotePathProjector = class {
+  constructor(mountPath) {
+    this.mountPath = mountPath;
+    const invalid = validatePath(mountPath);
+    if (invalid !== null) throw remoteProtocolError(`invalid remote mount path '${mountPath}'`);
+  }
+  mountPath;
+  childPath(localPath) {
+    if (localPath === this.mountPath) return "";
+    if (!localPath.startsWith(`${this.mountPath}/`)) {
+      throw remoteProtocolError(`local path '${localPath}' escapes remote mount '${this.mountPath}'`);
+    }
+    return localPath.slice(this.mountPath.length + 1);
+  }
+  localPath(childPath, allowRoot = true) {
+    const canonical = canonicalRemotePath(childPath, allowRoot);
+    return canonical === "" ? this.mountPath : `${this.mountPath}/${canonical}`;
+  }
+  childCommandPath(path) {
+    if (!path.startsWith("/") || path.startsWith("//")) {
+      throw remoteProtocolError(`remote ~help returned invalid command path '${path}'`);
+    }
+    return canonicalRemotePath(path.slice(1), false);
+  }
+  projectHelp(help, requestedLocalPath, ctx) {
+    const expectedChildPath = this.childPath(requestedLocalPath);
+    const nodeChildPath = canonicalRemotePath(help.node.path, expectedChildPath === "");
+    if (nodeChildPath !== expectedChildPath) {
+      throw remoteProtocolError(
+        `remote ~help path '${nodeChildPath}' does not match request '${expectedChildPath}'`
+      );
+    }
+    const nodePath = this.localPath(nodeChildPath, true);
+    const cmds = help.cmds.map((command) => {
+      const childCommandPath = this.childCommandPath(command.path);
+      if (!remotePathWithin(nodeChildPath, childCommandPath)) {
+        throw remoteProtocolError(`remote ~help command '${command.path}' escapes its node`);
+      }
+      return { ...command, path: `/${this.localPath(childCommandPath, false)}` };
+    });
+    const children = help.children?.map((child) => {
+      const childPath = canonicalRemotePath(child.path, false);
+      const parent = childPath.split("/").slice(0, -1).join("/");
+      if (parent !== nodeChildPath) {
+        throw remoteProtocolError(`remote ~help child '${childPath}' is not a direct descendant`);
+      }
+      return { ...child, path: this.localPath(childPath, false) };
+    }).filter((child) => ctx === void 0 || visibleRemotePath(ctx, child.path, child.kind));
+    return {
+      node: { ...help.node, path: nodePath },
+      cmds,
+      ...children === void 0 ? {} : { children },
+      ...help.feedback === void 0 ? {} : { feedback: help.feedback },
+      ...help.hint === void 0 ? {} : { hint: help.hint },
+      ...help.note === void 0 ? {} : { note: help.note }
+    };
   }
-  const out = {
-    path: `${mountPath}/${rel}`,
-    kind: entry.kind,
-    description: entry.description
-  };
-  if (entry.presence !== void 0) out.presence = entry.presence;
-  return out;
+  projectTree(tree, requestedLocalPath, ctx) {
+    const expectedChildPath = this.childPath(requestedLocalPath);
+    const rootChildPath = canonicalRemotePath(tree.path, expectedChildPath === "");
+    if (rootChildPath !== expectedChildPath) {
+      throw remoteProtocolError(
+        `remote ~tree path '${rootChildPath}' does not match request '${expectedChildPath}'`
+      );
+    }
+    const walk = (node, childPath) => {
+      const localPath = this.localPath(childPath, childPath === "");
+      const children = (node.children ?? []).map((child) => {
+        const canonical = canonicalRemotePath(child.path, false);
+        const parent = canonical.split("/").slice(0, -1).join("/");
+        if (parent !== childPath) {
+          throw remoteProtocolError(`remote ~tree child '${canonical}' is not a direct descendant`);
+        }
+        return walk(child, canonical);
+      }).filter((child) => visibleRemotePath(ctx, child.path, child.kind));
+      return {
+        path: localPath,
+        kind: node.kind,
+        description: node.description,
+        ...children.length === 0 ? {} : { children },
+        ...node.presence === void 0 ? {} : { presence: node.presence },
+        ...node.truncated === void 0 ? {} : { truncated: node.truncated }
+      };
+    };
+    return walk(tree, rootChildPath);
+  }
+};
+async function remotePathProjectorIfMatch(registry, treePath) {
+  const resolved = await registry.resolve(treePath).catch(() => null);
+  if (resolved === null || resolved.node.kind !== "remote" || resolved.node.config?.kind !== "remote") {
+    return null;
+  }
+  return new RemotePathProjector(resolved.node.path);
 }
 async function resolveRemoteSettings(state, base) {
   const runtime = await new RemoteAllowlistStore(state).hosts();
@@ -37051,6 +37406,17 @@ async function remotePassthroughIfMatch(c, ctx, registry, treePath, reservedTail
   }
   const requestPath = reservedTail === null ? treePath : `${treePath}/${reservedTail}`;
   const body = method === "POST" ? await c.req.text() : void 0;
+  const outboundHeaders = new Headers(headers);
+  const searchSettings = federatedSearchSettings(deps.remote);
+  const rawRemaining = outboundHeaders.get(SEARCH_REMAINING_MS_HEADER);
+  const requestedRemaining = rawRemaining !== null && /^\d+$/u.test(rawRemaining) ? Number(rawRemaining) : void 0;
+  const remainingMs = requestedRemaining !== void 0 && Number.isSafeInteger(requestedRemaining) && requestedRemaining > 0 ? Math.min(requestedRemaining, searchSettings.totalDeadlineMs) : void 0;
+  if (remainingMs !== void 0) {
+    outboundHeaders.set(
+      SEARCH_REMAINING_MS_HEADER,
+      String(Math.max(1, remainingMs - searchSettings.perHopReturnReserveMs))
+    );
+  }
   return await passthroughRemote({
     actor: { keyId: ctx.keyId, owner: ctx.owner, traceId: ctx.traceId },
     config: node.config,
@@ -37058,7 +37424,11 @@ async function remotePassthroughIfMatch(c, ctx, registry, treePath, reservedTail
     requestPath,
     method,
     ...body !== void 0 ? { body } : {},
-    headers,
+    headers: outboundHeaders,
+    ...remainingMs === void 0 ? {} : {
+      maxResponseBodyBytes: searchSettings.maxResponseBodyBytes,
+      signal: AbortSignal.timeout(remainingMs)
+    },
     secrets: deps.secrets,
     settings: await resolveRemoteSettings(deps.state, deps.remote),
     requestUrl: c.req.url
@@ -37082,15 +37452,14 @@ async function remoteTreeChildren(c, ctx, registry, treePath, deps) {
       retryable: resp.status >= 500
     });
   }
-  const remoteTree = await resp.json().catch(() => null);
-  if (remoteTree === null) {
+  const rawRemoteTree = await resp.json().catch(() => null);
+  const parsedRemoteTree = treeJsonSchema.safeParse(rawRemoteTree);
+  if (!parsedRemoteTree.success) {
     throw new TBError("unavailable", "remote ~tree returned invalid JSON", { retryable: false });
   }
-  const remotePath = canonicalRemotePath(remoteTree.path, true);
-  if (remotePath !== resolved.rest) {
-    throw remoteProtocolError(`remote ~tree path '${remotePath}' does not match request`);
-  }
-  return (remoteTree.children ?? []).map((child) => localizeRemoteEntry(resolved.node.path, remotePath, child));
+  const projector = new RemotePathProjector(resolved.node.path);
+  const projected = projector.projectTree(parsedRemoteTree.data, treePath, ctx);
+  return projected.children ?? [];
 }
 function assertRemoteConfigAllowed(config, settings) {
   if (config === null || typeof config !== "object") return;
@@ -37164,6 +37533,7 @@ async function handleRegister(c, env) {
   }
   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);
@@ -37230,7 +37600,9 @@ async function handleAuthorize(c, env) {
     encryptionKey: encKey,
     nodePath: path,
     serverUrl: node.config.url,
+    secrets: deps.secrets,
     origin: deps.canonicalOrigin ?? new URL(c.req.url).origin,
+    ...node.config.oauthClient !== void 0 ? { oauthClient: node.config.oauthClient } : {},
     ...redirectUri !== void 0 ? { redirectUri } : {}
   });
   return new Response(JSON.stringify(oauthAuthorizeResponseSchema.parse(result)), {
@@ -37574,15 +37946,25 @@ function registerPublicRoutes(app, env) {
       if (node.kind !== "mcp" || node.config?.kind !== "mcp" || node.config.auth !== "oauth") {
         return renderOAuthCallbackHtml(false, "target node is not an OAuth-backed mount");
       }
+      const currentClient = node.config.oauthClient;
+      if (payload.o === void 0 !== (currentClient === void 0) || payload.o !== void 0 && (currentClient?.clientId !== payload.o.i || currentClient.clientSecretRef !== payload.o.r)) {
+        return renderOAuthCallbackHtml(
+          false,
+          "OAuth client configuration changed; restart authorization"
+        );
+      }
       try {
         await finishMcpAuthorization({
           store: deps.state,
           encryptionKey: encKey,
           nodePath: payload.p,
           serverUrl: node.config.url,
+          secrets: deps.secrets,
           origin: deps.canonicalOrigin ?? new URL(c.req.url).origin,
           code,
           codeVerifier: payload.v,
+          ...q.iss !== void 0 ? { authorizationResponseIssuer: q.iss } : {},
+          ...node.config.oauthClient !== void 0 ? { oauthClient: node.config.oauthClient } : {},
           // 本地回调通道(CLI --local):兑换必须复用授权时的 redirect_uri。
           ...payload.r !== void 0 ? { redirectUri: payload.r } : {}
         });
@@ -37595,7 +37977,1505 @@ function registerPublicRoutes(app, env) {
   );
 }
 
+// ../app/src/search/federatedSession.ts
+var FEDERATED_SEARCH_HANDLE_PREFIX = "fsc1_";
+var FEDERATED_SEARCH_HANDLE_RANDOM_BYTES = 24;
+var FEDERATED_SEARCH_HANDLE_LENGTH = 37;
+var FEDERATED_SEARCH_SESSION_KEY_PREFIX = "fsearch:session:v1:";
+var FEDERATED_SEARCH_QUOTA_KEY = "fsearch:quota:v1";
+var HANDLE_PATTERN = /^fsc1_[A-Za-z0-9_-]{32}$/;
+var MAX_SAFE_JSON_DEPTH = 64;
+var MAX_SAFE_JSON_NODES = 1e4;
+var DEFAULT_MAX_RECORD_BYTES = 1024 * 1024;
+var DEFAULT_MAX_BYTES_GLOBAL = 128 * 1024 * 1024;
+var DEFAULT_MAX_BYTES_PER_ACTOR = 32 * 1024 * 1024;
+var DEFAULT_MAX_BYTES_PER_SESSION = 8 * 1024 * 1024;
+var DEFAULT_MAX_GENERATIONS_PER_SESSION = 1024;
+var DEFAULT_MAX_SESSIONS_GLOBAL = 256;
+var DEFAULT_MAX_SESSIONS_PER_ACTOR = 64;
+var QUOTA_CAS_ATTEMPTS = 32;
+var FORBIDDEN_STATE_KEYS = /* @__PURE__ */ new Set([
+  "$schema",
+  "authorization",
+  "baseurl",
+  "credential",
+  "inputschema",
+  "outputschema",
+  "schema",
+  "secret",
+  "sk",
+  "token"
+]);
+function sessionUnavailable(message) {
+  return new TBError("unavailable", message, { retryable: false });
+}
+function invalidSession() {
+  return new TBError("invalid_argument", "federated search session is invalid or expired", {
+    retryable: false
+  });
+}
+function corruptSession() {
+  return new TBError("internal", "federated search session state is corrupt", {
+    retryable: false
+  });
+}
+function isPlainObject3(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(value, expected) {
+  const actual = Object.keys(value).sort();
+  const sortedExpected = [...expected].sort();
+  return actual.length === sortedExpected.length && actual.every((key, index) => key === sortedExpected[index]);
+}
+function validOpaque(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 256 && !/[\0\r\n]/u.test(value);
+}
+function validExpiry(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function normalizedStateKey(key) {
+  return key.replaceAll("-", "").replaceAll("_", "").toLowerCase();
+}
+function safeStateValue(value, state, depth = 0) {
+  state.nodes++;
+  if (state.nodes > MAX_SAFE_JSON_NODES || depth > MAX_SAFE_JSON_DEPTH) {
+    throw new Error("federated search session value exceeds structural limits");
+  }
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("non-finite number");
+    return value;
+  }
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((item) => safeStateValue(item, state, depth + 1)));
+  }
+  if (!isPlainObject3(value)) throw new Error("non-JSON value");
+  const clone = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (FORBIDDEN_STATE_KEYS.has(normalizedStateKey(key))) {
+      throw new Error(`forbidden state field '${key}'`);
+    }
+    clone[key] = safeStateValue(item, state, depth + 1);
+  }
+  return Object.freeze(clone);
+}
+function parseRecord(value) {
+  if (!isPlainObject3(value) || !hasExactKeys(value, [
+    "actorKeyId",
+    "excludedStatuses",
+    "expiresAt",
+    "federationPolicy",
+    "generation",
+    "nextHandle",
+    "page",
+    "rankingVersion",
+    "requestDigest",
+    "revision",
+    "sessionId",
+    "sourceContinuations",
+    "topologyDigest"
+  ])) {
+    throw corruptSession();
+  }
+  if (value.revision !== 0 || !validOpaque(value.sessionId) || !validOpaque(value.actorKeyId) || !validOpaque(value.requestDigest) || !validOpaque(value.rankingVersion) || !validOpaque(value.topologyDigest) || !validExpiry(value.expiresAt) || !Number.isSafeInteger(value.generation) || value.generation < 0 || value.nextHandle !== null && (typeof value.nextHandle !== "string" || !HANDLE_PATTERN.test(value.nextHandle))) {
+    throw corruptSession();
+  }
+  try {
+    const state = { nodes: 0 };
+    return Object.freeze({
+      actorKeyId: value.actorKeyId,
+      excludedStatuses: safeStateValue(value.excludedStatuses, state),
+      expiresAt: value.expiresAt,
+      federationPolicy: safeStateValue(value.federationPolicy, state),
+      generation: value.generation,
+      nextHandle: value.nextHandle,
+      page: safeStateValue(value.page, state),
+      rankingVersion: value.rankingVersion,
+      requestDigest: value.requestDigest,
+      revision: 0,
+      sessionId: value.sessionId,
+      sourceContinuations: safeStateValue(value.sourceContinuations, state),
+      topologyDigest: value.topologyDigest
+    });
+  } catch (error) {
+    if (error instanceof TBError) throw error;
+    throw corruptSession();
+  }
+}
+function parseCreate(handle, input) {
+  try {
+    return parseRecord({
+      ...input,
+      revision: 0,
+      sessionId: input.sessionId ?? handle
+    });
+  } catch {
+    throw new TBError("invalid_argument", "federated search session input is invalid", {
+      retryable: false
+    });
+  }
+}
+function parseQuotaRecord(value) {
+  if (!isPlainObject3(value) || !hasExactKeys(value, ["revision", "sessions"])) {
+    throw corruptSession();
+  }
+  if (!Number.isSafeInteger(value.revision) || value.revision < 0 || !Array.isArray(value.sessions)) {
+    throw corruptSession();
+  }
+  const sessions = value.sessions.map((item) => {
+    if (!isPlainObject3(item) || !hasExactKeys(item, [
+      "actorKeyId",
+      "bytes",
+      "expiresAt",
+      "generation",
+      "generationBytes",
+      "generationId",
+      "id"
+    ]) || !validOpaque(item.actorKeyId) || !validExpiry(item.expiresAt) || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || !Number.isSafeInteger(item.generation) || item.generation < 0 || !Number.isSafeInteger(item.generationBytes) || item.generationBytes < 1 || typeof item.generationId !== "string" || !/^[0-9a-f]{64}$/u.test(item.generationId) || typeof item.id !== "string" || !/^[0-9a-f]{64}$/u.test(item.id)) {
+      throw corruptSession();
+    }
+    return {
+      actorKeyId: item.actorKeyId,
+      bytes: item.bytes,
+      expiresAt: item.expiresAt,
+      generation: item.generation,
+      generationBytes: item.generationBytes,
+      generationId: item.generationId,
+      id: item.id
+    };
+  });
+  return { revision: value.revision, sessions };
+}
+function isFederatedSearchSessionHandle(value) {
+  return typeof value === "string" && value.length === FEDERATED_SEARCH_HANDLE_LENGTH && HANDLE_PATTERN.test(value);
+}
+async function federatedSearchSessionStateKey(handle) {
+  if (!isFederatedSearchSessionHandle(handle)) throw invalidSession();
+  return FEDERATED_SEARCH_SESSION_KEY_PREFIX + await sha256Hex(handle);
+}
+var FederatedSearchSessionStore = class {
+  constructor(state, opts = {}) {
+    this.state = state;
+    if (state.compareAndSwap === void 0) {
+      throw sessionUnavailable("federated search sessions require StateStore.compareAndSwap");
+    }
+    this.cas = state.compareAndSwap.bind(state);
+    this.maxBytesGlobal = opts.maxBytesGlobal ?? DEFAULT_MAX_BYTES_GLOBAL;
+    this.maxBytesPerActor = opts.maxBytesPerActor ?? DEFAULT_MAX_BYTES_PER_ACTOR;
+    this.maxBytesPerSession = opts.maxBytesPerSession ?? DEFAULT_MAX_BYTES_PER_SESSION;
+    this.maxGenerationsPerSession = opts.maxGenerationsPerSession ?? DEFAULT_MAX_GENERATIONS_PER_SESSION;
+    this.maxRecordBytes = opts.maxRecordBytes ?? DEFAULT_MAX_RECORD_BYTES;
+    this.maxSessionsGlobal = opts.maxSessionsGlobal ?? DEFAULT_MAX_SESSIONS_GLOBAL;
+    this.maxSessionsPerActor = opts.maxSessionsPerActor ?? DEFAULT_MAX_SESSIONS_PER_ACTOR;
+    this.now = opts.now ?? (() => Date.now());
+    this.randomBytes = opts.randomBytes ?? ((length) => crypto.getRandomValues(new Uint8Array(length)));
+  }
+  state;
+  cas;
+  now;
+  randomBytes;
+  maxBytesGlobal;
+  maxBytesPerActor;
+  maxBytesPerSession;
+  maxGenerationsPerSession;
+  maxRecordBytes;
+  maxSessionsGlobal;
+  maxSessionsPerActor;
+  async cleanupExpiredSessionRows() {
+    const page = await this.state.list(FEDERATED_SEARCH_SESSION_KEY_PREFIX, { limit: 32 });
+    for (const item of page.items) {
+      let record2;
+      try {
+        record2 = parseRecord(item.value);
+      } catch {
+        continue;
+      }
+      if (Date.parse(record2.expiresAt) <= this.now()) {
+        await this.state.delete(item.key).catch(() => {
+        });
+      }
+    }
+  }
+  async reserveQuota(handle, record2, recordBytes) {
+    const id = await sha256Hex(record2.sessionId);
+    const generationId = await sha256Hex(handle);
+    for (let attempt2 = 0; attempt2 < QUOTA_CAS_ATTEMPTS; attempt2++) {
+      const raw = await this.state.get(FEDERATED_SEARCH_QUOTA_KEY);
+      const current = raw === null ? { revision: 0, sessions: [] } : parseQuotaRecord(raw);
+      const active = current.sessions.filter((entry) => Date.parse(entry.expiresAt) > this.now());
+      const existing = active.find((entry) => entry.id === id);
+      let nextEntry;
+      if (existing !== void 0) {
+        if (existing.actorKeyId !== record2.actorKeyId || existing.expiresAt !== record2.expiresAt) throw invalidSession();
+        if (record2.generation === existing.generation) {
+          if (existing.generationId !== generationId || existing.generationBytes !== recordBytes) throw invalidSession();
+          return;
+        }
+        if (record2.generation !== existing.generation + 1 || generationId === existing.generationId) throw invalidSession();
+        nextEntry = {
+          ...existing,
+          bytes: existing.bytes + recordBytes,
+          generation: record2.generation,
+          generationBytes: recordBytes,
+          generationId
+        };
+      } else {
+        if (record2.generation !== 0) throw invalidSession();
+        nextEntry = {
+          actorKeyId: record2.actorKeyId,
+          bytes: recordBytes,
+          expiresAt: record2.expiresAt,
+          generation: 0,
+          generationBytes: recordBytes,
+          generationId,
+          id
+        };
+      }
+      const actorCount = active.filter((entry) => entry.actorKeyId === record2.actorKeyId).length;
+      const globalBytes = active.reduce((total, entry) => total + entry.bytes, 0);
+      const actorBytes = active.filter((entry) => entry.actorKeyId === record2.actorKeyId).reduce((total, entry) => total + entry.bytes, 0);
+      const priorBytes = existing?.bytes ?? 0;
+      if (record2.generation >= this.maxGenerationsPerSession || nextEntry.bytes > this.maxBytesPerSession) {
+        throw new TBError("rate_limited", "federated search session chain quota exceeded", {
+          retryable: false
+        });
+      }
+      if (existing === void 0 && active.length >= this.maxSessionsGlobal || existing === void 0 && actorCount >= this.maxSessionsPerActor || globalBytes - priorBytes + nextEntry.bytes > this.maxBytesGlobal || actorBytes - priorBytes + nextEntry.bytes > this.maxBytesPerActor) {
+        throw new TBError("rate_limited", "federated search session quota exceeded", {
+          retryable: true
+        });
+      }
+      const next = {
+        revision: raw === null ? 0 : current.revision + 1,
+        sessions: [
+          ...active.filter((entry) => entry.id !== id),
+          nextEntry
+        ]
+      };
+      if (await this.cas(
+        FEDERATED_SEARCH_QUOTA_KEY,
+        raw === null ? null : current.revision,
+        next
+      )) return;
+    }
+    throw new TBError("unavailable", "federated search session quota is busy", {
+      retryable: true
+    });
+  }
+  issueHandle() {
+    const bytes = this.randomBytes(FEDERATED_SEARCH_HANDLE_RANDOM_BYTES);
+    if (!(bytes instanceof Uint8Array) || bytes.length !== FEDERATED_SEARCH_HANDLE_RANDOM_BYTES) {
+      throw sessionUnavailable("federated search session randomness is unavailable");
+    }
+    const handle = FEDERATED_SEARCH_HANDLE_PREFIX + base64urlEncode(bytes);
+    if (!isFederatedSearchSessionHandle(handle)) {
+      throw sessionUnavailable("federated search session randomness is invalid");
+    }
+    return handle;
+  }
+  async create(handle, input) {
+    const key = await federatedSearchSessionStateKey(handle);
+    const record2 = parseCreate(handle, input);
+    if (Date.parse(record2.expiresAt) <= this.now()) throw invalidSession();
+    const recordBytes = new TextEncoder().encode(JSON.stringify(record2)).length;
+    if (recordBytes > this.maxRecordBytes) {
+      throw new TBError("rate_limited", "federated search session record is too large", {
+        retryable: false
+      });
+    }
+    if (await this.state.get(key) !== null) return await this.read(handle, input);
+    if (record2.generation === 0) await this.cleanupExpiredSessionRows();
+    await this.reserveQuota(handle, record2, recordBytes);
+    if (await this.cas(key, null, record2)) {
+      return record2;
+    }
+    return await this.read(handle, input);
+  }
+  async createNew(input) {
+    const handle = this.issueHandle();
+    return { handle, record: await this.create(handle, input) };
+  }
+  async read(handle, binding) {
+    if (!validOpaque(binding.actorKeyId) || !validOpaque(binding.requestDigest)) {
+      throw invalidSession();
+    }
+    const raw = await this.state.get(await federatedSearchSessionStateKey(handle));
+    if (raw === null) throw invalidSession();
+    const record2 = parseRecord(raw);
+    if (Date.parse(record2.expiresAt) <= this.now()) {
+      await this.state.delete(await federatedSearchSessionStateKey(handle)).catch(() => {
+      });
+      throw invalidSession();
+    }
+    if (record2.actorKeyId !== binding.actorKeyId || record2.requestDigest !== binding.requestDigest) {
+      throw invalidSession();
+    }
+    return record2;
+  }
+};
+
+// ../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;
+  const compact = { ...tool };
+  delete compact.inputSchema;
+  delete compact.outputSchema;
+  if (compact.description !== void 0) {
+    const encoder = new TextEncoder();
+    if (encoder.encode(compact.description).length > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) {
+      let description = "";
+      let bytes = 0;
+      for (const char of compact.description) {
+        const size = encoder.encode(char).length;
+        if (bytes + size > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) break;
+        description += char;
+        bytes += size;
+      }
+      compact.description = description;
+    }
+  }
+  return compact;
+}
+async function executeLocalSearch(deps, request) {
+  const { ctx, search, searchSync, state } = deps;
+  const query = request.query;
+  const wireOpts = request.opts ?? {};
+  const detail = wireOpts.detail ?? "compact";
+  const matching = wireOpts.matching ?? "best";
+  const mode = wireOpts.mode ?? "keyword";
+  const limit = normalizeToolSearchLimit(wireOpts.limit);
+  const constraints = normalizeToolSearchOptions({
+    ...wireOpts.effects === void 0 ? {} : { effects: wireOpts.effects },
+    matching,
+    ...wireOpts.minCoverage === void 0 ? {} : { minCoverage: wireOpts.minCoverage },
+    ...wireOpts.pathPrefix === void 0 ? {} : { pathPrefix: wireOpts.pathPrefix }
+  });
+  const indexOptions = { mode, ...constraints };
+  await searchSync?.ensureReady();
+  const registry = new NodeRegistryStore(state);
+  const selected = [];
+  const workLimit = Math.min(
+    TOOL_SEARCH_WORK_LIMIT,
+    Math.max(TOOL_SEARCH_BATCH_LIMIT, limit * 2)
+  );
+  let scanCursor = wireOpts.cursor;
+  let responseCursor;
+  let responseCandidate;
+  let visibleCoverage;
+  let scanned = 0;
+  let stopped = false;
+  while (!stopped && selected.length < limit && scanned < workLimit) {
+    const batchLimit = Math.min(TOOL_SEARCH_BATCH_LIMIT, workLimit - scanned);
+    const page = await search.search(query, {
+      ...indexOptions,
+      limit: batchLimit,
+      ...scanCursor === void 0 ? {} : { cursor: scanCursor }
+    });
+    if (page.items.length === 0) {
+      responseCursor = page.cursor;
+      break;
+    }
+    const nodes = await registry.getMany(page.items.map((candidate) => candidate.path));
+    let lastCandidateInVisibleBand;
+    for (const [index, candidate] of page.items.entries()) {
+      if (matching === "best" && visibleCoverage !== void 0 && candidate.coverage !== visibleCoverage) {
+        responseCandidate = lastCandidateInVisibleBand;
+        responseCursor = responseCandidate === void 0 ? scanCursor : void 0;
+        stopped = true;
+        break;
+      }
+      scanned++;
+      lastCandidateInVisibleBand = candidate;
+      if (!check(ctx, candidate.path, "read").allow || !check(ctx, candidate.path, "call").allow) {
+        continue;
+      }
+      const node = nodes.get(candidate.path);
+      if (node === void 0 || node.kind !== "mcp" && node.kind !== "http" && node.kind !== "tool" || node.config?.kind !== node.kind || virtualizeTools(node.virtualize, [{ name: candidate.name }]).exposed.length === 0) {
+        continue;
+      }
+      visibleCoverage ??= candidate.coverage;
+      selected.push({ candidate, node });
+      if (selected.length === limit) {
+        const hasUnscanned = index < page.items.length - 1 || page.cursor !== void 0;
+        responseCandidate = hasUnscanned ? candidate : void 0;
+        responseCursor = void 0;
+        stopped = true;
+        break;
+      }
+    }
+    if (stopped) break;
+    responseCursor = page.cursor;
+    if (page.cursor === void 0) break;
+    scanCursor = page.cursor;
+  }
+  const canonicalTools = await canonicalSearchTools(state, selected.map((item) => item.node));
+  const requestedEffects = constraints.effects === void 0 ? void 0 : new Set(constraints.effects);
+  const items = [];
+  let pageBytes = 0;
+  for (const [index, selectedItem] of selected.entries()) {
+    const raw = canonicalTools.get(selectedItem.candidate.path)?.find((tool2) => tool2.name === selectedItem.candidate.name);
+    if (raw === void 0) continue;
+    const tool = virtualizeTools(selectedItem.node.virtualize, [raw]).exposed[0];
+    if (tool === void 0) continue;
+    if (requestedEffects !== void 0 && !requestedEffects.has(normalizedEffect(tool.effect))) {
+      continue;
+    }
+    const item = {
+      path: selectedItem.candidate.path,
+      relevance: {
+        coverage: selectedItem.candidate.coverage,
+        matchedTermCount: selectedItem.candidate.matchedTermCount,
+        rankingVersion: "keyword-v2",
+        totalTermCount: selectedItem.candidate.totalTermCount
+      },
+      tool: projectSearchTool(tool, detail)
+    };
+    const itemBytes = new TextEncoder().encode(JSON.stringify(item)).length;
+    if (pageBytes + itemBytes > TOOL_SEARCH_PAGE_BYTES) {
+      if (items.length === 0) {
+        throw new TBError("internal", "\u5DE5\u5177\u641C\u7D22\u9875\u9762\u5B57\u8282\u9884\u7B97\u65E0\u6CD5\u5BB9\u7EB3\u9996\u4E2A\u7ED3\u679C");
+      }
+      responseCandidate = selected[index - 1]?.candidate;
+      responseCursor = void 0;
+      break;
+    }
+    items.push(item);
+    pageBytes += itemBytes;
+  }
+  if (responseCandidate !== void 0) {
+    responseCursor = await search.cursorFor(query, responseCandidate, mode);
+  }
+  if (items.length === 0) responseCursor = void 0;
+  return responseCursor === void 0 ? { items } : { items, cursor: responseCursor };
+}
+
+// ../app/src/search/federatedSearch.ts
+var HEADER_REMAINING_MS = "x-tb-search-remaining-ms";
+var HEADER_SESSION_TTL_MS = "x-tb-search-session-ttl-ms";
+var HEADER_SOURCE_BUDGET = "x-tb-search-source-budget";
+var HEADER_VALIDATE_SNAPSHOT = "x-tb-search-validate-snapshot";
+var HEADER_VIA = "x-tb-via";
+var HEADER_WANT_SNAPSHOT = "x-tb-search-want-snapshot";
+function clampHeader(value, local) {
+  if (value === null || !/^\d+$/u.test(value)) return local;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? Math.min(parsed, local) : local;
+}
+function isPrefix(prefix, path) {
+  return prefix === "" || prefix === path || path.startsWith(`${prefix}/`);
+}
+function controlledStatus(error) {
+  if (error instanceof TBError) {
+    if (error.message.includes("\u73AF")) return "cycle";
+    if (error.message.includes("\u8DF3\u6570")) return "hop_limit";
+    if (error.message.includes("aborted")) return "timed_out";
+    if (error.message.includes("work budget")) return "budget_exhausted";
+  }
+  return "unavailable";
+}
+function retryableContinuationError() {
+  return new TBError("unavailable", "federated search continuation source unavailable", {
+    retryable: true
+  });
+}
+function invalidContinuation() {
+  return new TBError("invalid_argument", "federated search cursor no longer matches topology", {
+    retryable: false
+  });
+}
+function continuationSourceError(error) {
+  if (error instanceof TBError) {
+    if (error.code === "invalid_argument") return error;
+    if (error.message.includes("source work budget exhausted")) return invalidContinuation();
+  }
+  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 };
+}
+function normalizedEffect2(effect) {
+  return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
+}
+function requestConstraints(request) {
+  return normalizeToolSearchOptions({
+    ...request.opts?.effects === void 0 ? {} : { effects: request.opts.effects },
+    matching: request.opts?.matching ?? "best",
+    ...request.opts?.minCoverage === void 0 ? {} : { minCoverage: request.opts.minCoverage },
+    ...request.opts?.pathPrefix === void 0 ? {} : { pathPrefix: request.opts.pathPrefix }
+  });
+}
+function assertHardResultConstraints(item, constraints) {
+  const effects = constraints.effects === void 0 ? void 0 : new Set(constraints.effects);
+  if (constraints.pathPrefix !== void 0 && !isPrefix(constraints.pathPrefix, item.path) || constraints.minCoverage !== void 0 && item.relevance.coverage < constraints.minCoverage || effects !== void 0 && !effects.has(normalizedEffect2(item.tool.effect))) {
+    throw new TBError("unavailable", "remote search violated a hard result constraint", {
+      retryable: false
+    });
+  }
+}
+function sourceStatusKey(value) {
+  return `${value.path}\0${value.status}`;
+}
+function mergeStatuses(...groups) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of groups.flat()) {
+    const key = sourceStatusKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out.sort((left, right) => left.path.localeCompare(right.path) || left.status.localeCompare(right.status));
+}
+function responseHasMore(sources) {
+  return sources.some((source) => source.pending !== void 0 || !source.done);
+}
+function serializableSources(sources) {
+  return sources.map((source) => ({
+    balanceCount: source.balanceCount,
+    ...source.balanceCoverage === void 0 ? {} : { balanceCoverage: source.balanceCoverage },
+    budget: source.budget,
+    done: source.done,
+    ...source.excluded === void 0 ? {} : { excluded: source.excluded },
+    kind: source.kind,
+    path: source.path,
+    ...source.cursor === void 0 ? {} : { cursor: source.cursor },
+    ...source.nextCursor === void 0 ? {} : { nextCursor: source.nextCursor },
+    ...source.pending === void 0 ? {} : { pending: compactItem(source.pending) },
+    ...source.validationCursor === void 0 ? {} : { validationCursor: source.validationCursor }
+  }));
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const object2 = value;
+  return `{${Object.keys(object2).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object2[key])}`).join(",")}}`;
+}
+function sameJson(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+function assertNextRecord(current, next, topology) {
+  if (next.topologyDigest !== topology || next.rankingVersion !== TOOL_SEARCH_RANKING_VERSION || next.sessionId !== current.sessionId || next.generation !== current.generation + 1 || next.expiresAt !== current.expiresAt || !sameJson(next.federationPolicy, current.federationPolicy)) {
+    throw invalidContinuation();
+  }
+}
+function assertCachedPage(computed, cached) {
+  if (!sameJson(computed.page, cached.page) || !sameJson(computed.excluded, cached.excludedStatuses) || !sameJson(serializableSources(computed.sources), cached.sourceContinuations)) {
+    throw invalidContinuation();
+  }
+}
+function requestForDigest(request, limit) {
+  const opts = request.opts ?? {};
+  return {
+    query: request.query,
+    opts: {
+      effects: opts.effects ?? null,
+      federation: "recursive",
+      limit,
+      matching: opts.matching ?? "best",
+      minCoverage: opts.minCoverage ?? null,
+      mode: opts.mode ?? "keyword",
+      pathPrefix: opts.pathPrefix ?? null
+    }
+  };
+}
+async function topologyDigest(nodes, includeLocal, localRevision, remotePolicy) {
+  return await sha256Hex(canonicalJson({
+    local: includeLocal,
+    localRevision,
+    nodes: nodes.map((node) => ({
+      kind: node.kind,
+      path: node.path,
+      remote: node.config?.kind === "remote" ? { baseUrl: node.config.baseUrl, skRef: node.config.skRef ?? null } : null,
+      updatedAt: node.updatedAt ?? "",
+      virtualize: node.virtualize ?? null
+    })),
+    remotePolicy
+  }));
+}
+function directRemoteNodes(nodes) {
+  const remotes = nodes.filter((node) => node.kind === "remote" && node.config?.kind === "remote").sort((left, right) => left.path.localeCompare(right.path));
+  return remotes.filter((node) => !remotes.some((parent) => parent.path !== node.path && isPrefix(parent.path, node.path)));
+}
+function childPrefixFor(mount, pathPrefix) {
+  if (pathPrefix === void 0) return { eligible: true };
+  if (isPrefix(mount, pathPrefix)) {
+    const child = new RemotePathProjector(mount).childPath(pathPrefix);
+    return { eligible: true, ...child === "" ? {} : { pathPrefix: child } };
+  }
+  return { eligible: isPrefix(pathPrefix, mount) };
+}
+function localEligible(remotes, pathPrefix) {
+  return pathPrefix === void 0 || !remotes.some((node) => isPrefix(node.path, pathPrefix));
+}
+async function mapLimit(values, concurrency, fn) {
+  const results = new Array(values.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (next < values.length) {
+      const index = next++;
+      results[index] = await fn(values[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+function deadlineSignal(deadline) {
+  return AbortSignal.timeout(Math.max(1, Math.floor(deadline - Date.now())));
+}
+function federatedHeaders(inbound, remainingMs, sourceBudget, sessionTtlMs) {
+  const headers = new Headers();
+  headers.set("accept", "application/json");
+  headers.set("content-type", "application/json");
+  const via = inbound.get(HEADER_VIA);
+  if (via !== null) headers.set(HEADER_VIA, via);
+  headers.set(HEADER_REMAINING_MS, String(Math.max(1, Math.floor(remainingMs))));
+  headers.set(HEADER_SESSION_TTL_MS, String(Math.max(1, Math.floor(sessionTtlMs))));
+  headers.set(HEADER_SOURCE_BUDGET, String(Math.max(1, Math.floor(sourceBudget))));
+  headers.set(HEADER_WANT_SNAPSHOT, "1");
+  return headers;
+}
+function projectChildPage(mount, page, totalTermCount, ctx, request) {
+  const projector = new RemotePathProjector(mount);
+  const constraints = requestConstraints(request);
+  const items = page.items.map((item) => {
+    if (item.relevance.rankingVersion !== TOOL_SEARCH_RANKING_VERSION || item.relevance.totalTermCount !== totalTermCount || item.relevance.matchedTermCount < 1 || item.relevance.matchedTermCount > totalTermCount || item.relevance.coverage !== item.relevance.matchedTermCount / totalTermCount) {
+      throw new TBError("unavailable", "remote search returned incompatible relevance evidence", {
+        retryable: false
+      });
+    }
+    const path = projector.localPath(item.path, false);
+    const sourcePath = projector.localPath(item.source?.path ?? "", true);
+    if (item.tool.name.includes("/")) {
+      throw new TBError("unavailable", "remote search returned an unsafe tool name", {
+        retryable: false
+      });
+    }
+    try {
+      if (canonicalRemotePath(item.tool.name, false) !== item.tool.name.toLowerCase()) {
+        throw new Error("non-canonical");
+      }
+    } catch {
+      throw new TBError("unavailable", "remote search returned an unsafe tool name", {
+        retryable: false
+      });
+    }
+    if (!isPrefix(sourcePath, path)) {
+      throw new TBError("unavailable", "remote search source does not own its result", {
+        retryable: false
+      });
+    }
+    const projected = compactItem({ ...item, path, source: { path: sourcePath } });
+    assertHardResultConstraints(projected, constraints);
+    return projected;
+  }).filter((item) => check(ctx, item.path, "read").allow && check(ctx, item.path, "call").allow);
+  const projectedSources = page.sources?.map((source) => ({
+    path: projector.localPath(source.path, true),
+    status: source.status
+  }));
+  const sourceStatuses = /* @__PURE__ */ new Map();
+  for (const source of projectedSources ?? []) {
+    const previous = sourceStatuses.get(source.path);
+    if (previous !== void 0 && previous !== source.status) {
+      throw new TBError("unavailable", "remote search returned conflicting source statuses", {
+        retryable: false
+      });
+    }
+    sourceStatuses.set(source.path, source.status);
+  }
+  const hasFailure = [...sourceStatuses.values()].some((status) => status !== "ok");
+  if (page.partial === true !== hasFailure || page.cursor !== void 0 && !isFederatedSearchSessionHandle(page.cursor) || page.snapshot !== void 0 && !isFederatedSearchSessionHandle(page.snapshot)) {
+    throw new TBError("unavailable", "remote search returned inconsistent page metadata", {
+      retryable: false
+    });
+  }
+  const sources = projectedSources?.filter((source) => check(ctx, source.path, "read").allow && check(ctx, source.path, "call").allow);
+  const visiblePartial = sources?.some((source) => source.status !== "ok") === true;
+  return {
+    items,
+    ...page.cursor === void 0 ? {} : { cursor: page.cursor },
+    ...visiblePartial ? { partial: true } : {},
+    ...sources === void 0 ? {} : { sources }
+  };
+}
+async function remoteResponse(deps, input, node, requestPath, method, headers, deadline, body) {
+  if (node.config?.kind !== "remote") throw invalidContinuation();
+  return await passthroughRemote({
+    actor: {
+      keyId: input.ctx.keyId,
+      owner: input.ctx.owner,
+      traceId: input.ctx.traceId
+    },
+    ...body === void 0 ? {} : { body },
+    config: node.config,
+    headers,
+    maxResponseBodyBytes: federatedSearchSettings(deps.remote).maxResponseBodyBytes,
+    method,
+    nodePath: node.path,
+    requestPath,
+    requestUrl: input.requestUrl,
+    secrets: deps.secrets,
+    settings: await resolveRemoteSettings(input.state, deps.remote),
+    signal: deadlineSignal(deadline)
+  });
+}
+async function assertFederatedCapability(deps, input, node, headers, deadline) {
+  if (node.config?.kind !== "remote" || node.config.skRef === void 0) {
+    throw new TBError("unavailable", "remote search source is unsupported", { retryable: false });
+  }
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${node.path}/~describe`,
+    "GET",
+    headers,
+    deadline
+  );
+  if (!response.ok) {
+    throw new TBError("unavailable", "remote search capability is unavailable", {
+      retryable: response.status >= 500
+    });
+  }
+  const value = await response.json().catch(() => null);
+  if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(value.capabilities) || !value.capabilities.includes("search:federated")) {
+    throw new TBError("unavailable", "remote search source is unsupported", { retryable: false });
+  }
+}
+function childSearchRequest(input, source, cursor) {
+  const opts = input.request.opts ?? {};
+  const childPrefix = childPrefixFor(source.path, opts.pathPrefix).pathPrefix;
+  return {
+    query: input.request.query,
+    opts: {
+      ...opts.effects === void 0 ? {} : { effects: opts.effects },
+      ...cursor === void 0 ? {} : { cursor },
+      detail: "compact",
+      federation: "recursive",
+      limit: 1,
+      matching: opts.matching ?? "best",
+      ...opts.minCoverage === void 0 ? {} : { minCoverage: opts.minCoverage },
+      mode: "keyword",
+      ...childPrefix === void 0 ? {} : { pathPrefix: childPrefix }
+    }
+  };
+}
+async function throwChildSearchError(response) {
+  const error = await response.json().catch(() => null);
+  const message = typeof error?.message === "string" ? error.message : "";
+  if (message.includes("\u73AF")) {
+    throw new TBError("unavailable", "\u68C0\u6D4B\u5230\u900F\u4F20\u73AF", { retryable: false });
+  }
+  if (message.includes("\u8DF3\u6570")) {
+    throw new TBError("unavailable", "\u900F\u4F20\u8DF3\u6570\u8D85\u9650", { retryable: false });
+  }
+  if (response.status >= 400 && response.status < 500) throw invalidContinuation();
+  throw new TBError("unavailable", "remote search unavailable", {
+    retryable: response.status >= 500
+  });
+}
+async function fetchHead(deps, input, source, remoteNodes, deadline, expiresAt, totalTermCount, skipBudget = 20) {
+  if (source.done || source.pending !== void 0) return { statuses: [] };
+  const opts = input.request.opts ?? {};
+  if (source.kind === "local") {
+    const page2 = await executeLocalSearch(
+      {
+        ctx: input.ctx,
+        search: input.search,
+        state: input.state
+      },
+      {
+        query: input.request.query,
+        opts: {
+          ...opts.effects === void 0 ? {} : { effects: opts.effects },
+          ...source.cursor === void 0 ? {} : { cursor: source.cursor },
+          detail: "compact",
+          federation: "local",
+          limit: 1,
+          matching: opts.matching ?? "best",
+          ...opts.minCoverage === void 0 ? {} : { minCoverage: opts.minCoverage },
+          mode: "keyword",
+          ...opts.pathPrefix === void 0 ? {} : { pathPrefix: opts.pathPrefix }
+        }
+      }
+    );
+    const item2 = page2.items[0];
+    if (item2 === void 0) {
+      source.done = page2.cursor === void 0;
+      source.cursor = page2.cursor;
+      return { statuses: [] };
+    }
+    source.pending = compactItem({ ...item2, source: { path: "" } });
+    source.nextCursor = page2.cursor;
+    return { statuses: [] };
+  }
+  const node = remoteNodes.get(source.path);
+  if (node === void 0 || node.config?.kind !== "remote" || !check(input.ctx, node.path, "read").allow || !check(input.ctx, node.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const settings = federatedSearchSettings(deps.remote);
+  const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+  if (remainingMs < settings.minChildWorkMs) {
+    throw new TBError("unavailable", "federated search child has no remaining work budget", {
+      retryable: false
+    });
+  }
+  const headers = federatedHeaders(
+    input.headers,
+    remainingMs,
+    source.budget,
+    expiresAt - Date.now()
+  );
+  const childRequest = childSearchRequest(input, source, source.cursor);
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${node.path}/~search`,
+    "POST",
+    headers,
+    deadline,
+    JSON.stringify(childRequest)
+  );
+  if (!response.ok) await throwChildSearchError(response);
+  const parsed = toolSearchPageSchema.safeParse(await response.json().catch(() => null));
+  if (!parsed.success) {
+    throw new TBError("unavailable", "remote search returned invalid JSON", { retryable: false });
+  }
+  if (parsed.data.items.length > 1) {
+    throw new TBError("unavailable", "remote search exceeded the requested source batch size", {
+      retryable: false
+    });
+  }
+  if (!isFederatedSearchSessionHandle(parsed.data.snapshot)) {
+    throw new TBError("unavailable", "remote search omitted its validation snapshot", {
+      retryable: false
+    });
+  }
+  source.validationCursor = parsed.data.snapshot;
+  const page = projectChildPage(
+    source.path,
+    parsed.data,
+    totalTermCount,
+    input.ctx,
+    input.request
+  );
+  const item = page.items[0];
+  if (item === void 0) {
+    source.done = page.cursor === void 0;
+    source.cursor = page.cursor;
+    if (!source.done) {
+      if (skipBudget <= 1) {
+        throw new TBError("unavailable", "federated search source work budget exhausted", {
+          retryable: false
+        });
+      }
+      return await fetchHead(
+        deps,
+        input,
+        source,
+        remoteNodes,
+        deadline,
+        expiresAt,
+        totalTermCount,
+        skipBudget - 1
+      );
+    }
+  } else {
+    source.pending = item;
+    source.nextCursor = page.cursor;
+  }
+  return { statuses: page.sources?.filter((status) => status.status !== "ok") ?? [] };
+}
+async function validateSourceSnapshots(deps, input, sources, remoteNodes, deadline, expiresAt, maxConcurrency) {
+  const remotes = sources.filter((source) => source.kind === "remote" && source.excluded !== true);
+  await mapLimit(remotes, maxConcurrency, async (source) => {
+    const node = remoteNodes.get(source.path);
+    if (node === void 0 || source.validationCursor === void 0) throw invalidContinuation();
+    const settings = federatedSearchSettings(deps.remote);
+    const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+    if (remainingMs < settings.minChildWorkMs) throw retryableContinuationError();
+    const headers = federatedHeaders(
+      input.headers,
+      remainingMs,
+      source.budget,
+      expiresAt - Date.now()
+    );
+    headers.set(HEADER_VALIDATE_SNAPSHOT, "1");
+    const response = await remoteResponse(
+      deps,
+      input,
+      node,
+      `${node.path}/~search`,
+      "POST",
+      headers,
+      deadline,
+      JSON.stringify(childSearchRequest(input, source, source.validationCursor))
+    );
+    if (!response.ok) await throwChildSearchError(response);
+    const parsed = toolSearchPageSchema.safeParse(await response.json().catch(() => null));
+    if (!parsed.success || parsed.data.items.length !== 0 || parsed.data.cursor !== void 0 || parsed.data.snapshot !== void 0 || parsed.data.partial !== void 0 || parsed.data.sources !== void 0) throw invalidContinuation();
+  });
+}
+function consume(source) {
+  const item = source.pending;
+  if (item === void 0) throw new Error("federated source has no pending item");
+  source.pending = void 0;
+  source.cursor = source.nextCursor;
+  source.nextCursor = void 0;
+  source.done = source.cursor === void 0;
+  return item;
+}
+async function hydrateLocal(input, item) {
+  if (!check(input.ctx, item.path, "read").allow || !check(input.ctx, item.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const registry = new NodeRegistryStore(input.state);
+  const node = await registry.get(item.path).catch(() => null);
+  if (node === null || node.kind !== "mcp" && node.kind !== "http" && node.kind !== "tool" || node.config?.kind !== node.kind) {
+    throw invalidContinuation();
+  }
+  const raw = (await canonicalSearchTools(input.state, [node])).get(node.path);
+  if (raw === void 0) throw invalidContinuation();
+  const matches = virtualizeTools(node.virtualize, raw).exposed.filter((tool2) => tool2.name === item.tool.name);
+  if (matches.length !== 1) throw invalidContinuation();
+  const tool = matches[0];
+  if (tool === void 0) throw invalidContinuation();
+  return { ...item, tool };
+}
+async function hydrateRemote(deps, input, item, source, node, deadline) {
+  if (!check(input.ctx, source.path, "read").allow || !check(input.ctx, source.path, "call").allow || !check(input.ctx, item.path, "read").allow || !check(input.ctx, item.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${item.path}/${item.tool.name}/~help`,
+    "GET",
+    (() => {
+      const headers = new Headers({ accept: "application/json" });
+      const via = input.headers.get(HEADER_VIA);
+      if (via !== null) headers.set(HEADER_VIA, via);
+      headers.set(
+        HEADER_REMAINING_MS,
+        String(Math.max(1, Math.floor(deadline - Date.now())))
+      );
+      return headers;
+    })(),
+    deadline
+  );
+  if (!response.ok) {
+    if (response.status >= 400 && response.status < 500) throw invalidContinuation();
+    throw retryableContinuationError();
+  }
+  const parsed = helpJsonSchema.safeParse(await response.json().catch(() => null));
+  if (!parsed.success) throw invalidContinuation();
+  const projected = new RemotePathProjector(source.path).projectHelp(parsed.data, `${item.path}/${item.tool.name}`);
+  const commands = projected.cmds.filter((cmd) => cmd.name === item.tool.name && cmd.path === `/${item.path}/${item.tool.name}` && cmd.scope === "call");
+  if (commands.length !== 1) throw invalidContinuation();
+  const command = commands[0];
+  if (command === void 0) throw invalidContinuation();
+  const tool = {
+    name: command.name,
+    ...command.h === void 0 ? {} : { description: command.h },
+    ...command.effect === void 0 ? {} : { effect: command.effect },
+    ...command.confirm === void 0 ? {} : { confirm: command.confirm },
+    ...command.inputSchema === void 0 ? {} : { inputSchema: command.inputSchema },
+    ...command.outputSchema === void 0 ? {} : { outputSchema: command.outputSchema }
+  };
+  return { ...item, tool };
+}
+async function computePage(deps, input, sources, remoteNodes, deadline, expiresAt, totalTermCount, initial, initialExcluded, maxConcurrency) {
+  let excluded = [...initialExcluded];
+  if (!initial) {
+    await validateSourceSnapshots(
+      deps,
+      input,
+      sources,
+      remoteNodes,
+      deadline,
+      expiresAt,
+      maxConcurrency
+    );
+  }
+  const active = sources.filter((source) => !source.done);
+  const capabilityFailures = await mapLimit(
+    initial ? active.filter((source) => source.kind === "remote") : [],
+    maxConcurrency,
+    async (source) => {
+      const node = remoteNodes.get(source.path);
+      if (node === void 0) return { source, status: "invalid_response" };
+      const settings = federatedSearchSettings(deps.remote);
+      const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+      if (remainingMs < settings.minChildWorkMs) {
+        return { source, status: "budget_exhausted" };
+      }
+      const headers = federatedHeaders(
+        input.headers,
+        remainingMs,
+        source.budget,
+        expiresAt - Date.now()
+      );
+      try {
+        await assertFederatedCapability(deps, input, node, headers, deadline);
+        return null;
+      } catch (error) {
+        const status = error instanceof TBError && error.message.includes("unsupported") ? "unsupported" : controlledStatus(error);
+        return { error, source, status };
+      }
+    }
+  );
+  for (const failure of capabilityFailures) {
+    if (failure === null) continue;
+    if (!initial) {
+      if (failure.error instanceof TBError && failure.error.code === "invalid_argument") {
+        throw failure.error;
+      }
+      throw failure.status === "unsupported" ? invalidContinuation() : retryableContinuationError();
+    }
+    failure.source.done = true;
+    failure.source.excluded = true;
+    excluded = mergeStatuses(excluded, [{ path: failure.source.path, status: failure.status }]);
+  }
+  const storedPending = sources.filter((source) => source.pending !== void 0);
+  const refreshedStatuses = await mapLimit(storedPending, maxConcurrency, async (source) => {
+    try {
+      const pending = source.pending;
+      if (pending === void 0) throw invalidContinuation();
+      const hydrated = source.kind === "local" ? await hydrateLocal(input, pending) : await (async () => {
+        const node = remoteNodes.get(source.path);
+        if (node === void 0) throw invalidContinuation();
+        return await hydrateRemote(deps, input, pending, source, node, deadline);
+      })();
+      if (!sameJson(compactItem(hydrated), pending)) throw invalidContinuation();
+      return [];
+    } catch (error) {
+      throw continuationSourceError(error);
+    }
+  });
+  excluded = mergeStatuses(excluded, ...refreshedStatuses);
+  let successfulSources = storedPending.length;
+  const headResults = await mapLimit(
+    sources.filter((source) => !source.done && source.pending === void 0),
+    maxConcurrency,
+    async (source) => {
+      try {
+        const result = await fetchHead(
+          deps,
+          input,
+          source,
+          remoteNodes,
+          deadline,
+          expiresAt,
+          totalTermCount
+        );
+        return { ...result, success: true };
+      } catch (error) {
+        if (!initial) throw continuationSourceError(error);
+        source.done = true;
+        source.excluded = true;
+        return {
+          statuses: [{ path: source.path, status: controlledStatus(error) }],
+          success: false
+        };
+      }
+    }
+  );
+  successfulSources += headResults.filter((result) => result.success).length;
+  excluded = mergeStatuses(excluded, ...headResults.map((result) => result.statuses));
+  const items = [];
+  let selectedCoverage;
+  const limit = input.request.opts?.limit ?? 10;
+  while (items.length < limit) {
+    const heads = sources.filter((source2) => source2.pending !== void 0);
+    if (heads.length === 0) break;
+    const highest = Math.max(...heads.map((source2) => source2.pending?.relevance.coverage ?? -1));
+    selectedCoverage ??= highest;
+    if ((input.request.opts?.matching ?? "best") === "best" && highest !== selectedCoverage) break;
+    const bucket = heads.filter((source2) => source2.pending?.relevance.coverage === highest).sort((left, right) => (left.balanceCoverage === highest ? left.balanceCount : 0) - (right.balanceCoverage === highest ? right.balanceCount : 0) || left.path.localeCompare(right.path));
+    const source = bucket[0];
+    if (source === void 0) break;
+    items.push(consume(source));
+    if (source.balanceCoverage !== highest) {
+      source.balanceCoverage = highest;
+      source.balanceCount = 0;
+    }
+    source.balanceCount++;
+    try {
+      const result = await fetchHead(
+        deps,
+        input,
+        source,
+        remoteNodes,
+        deadline,
+        expiresAt,
+        totalTermCount
+      );
+      excluded = mergeStatuses(excluded, result.statuses);
+    } catch (error) {
+      if (!initial) throw continuationSourceError(error);
+      source.done = true;
+      source.excluded = true;
+      excluded = mergeStatuses(excluded, [{ path: source.path, status: controlledStatus(error) }]);
+    }
+  }
+  const partial = excluded.length > 0;
+  const page = {
+    items,
+    ...partial ? { partial: true, sources: excluded } : {}
+  };
+  return { excluded, page, sources, successfulSources };
+}
+function visibleSourceStatuses(ctx, page) {
+  const rawSources = page.sources;
+  const rest = { ...page };
+  delete rest.partial;
+  delete rest.sources;
+  const sources = rawSources?.filter((source) => check(ctx, source.path, "read").allow && check(ctx, source.path, "call").allow);
+  const partial = sources?.some((source) => source.status !== "ok") === true;
+  return {
+    ...rest,
+    ...partial ? { partial: true } : {},
+    ...sources === void 0 || sources.length === 0 ? {} : { sources }
+  };
+}
+async function hydratePage(deps, input, page, sources, remoteNodes, deadline, forceRevalidate = false) {
+  const visiblePage = visibleSourceStatuses(input.ctx, page);
+  const detail = input.request.opts?.detail ?? "compact";
+  if (detail !== "full" && !forceRevalidate) return visiblePage;
+  const constraints = requestConstraints(input.request);
+  const output = [];
+  const encoder = new TextEncoder();
+  let outputBytes = encoder.encode(JSON.stringify({ ...visiblePage, items: [] })).length;
+  const concurrency = federatedSearchSettings(deps.remote).maxConcurrency;
+  for (let offset = 0; offset < visiblePage.items.length; offset += concurrency) {
+    const batch = visiblePage.items.slice(offset, offset + concurrency);
+    const hydrated = await Promise.all(batch.map(async (item) => {
+      const direct = sources.find((source) => source.kind === "remote" && isPrefix(source.path, item.path));
+      const full = direct === void 0 ? await hydrateLocal(input, item) : await (async () => {
+        const node = remoteNodes.get(direct.path);
+        if (node === void 0) throw invalidContinuation();
+        return await hydrateRemote(deps, input, item, direct, node, deadline);
+      })();
+      if (!sameJson(compactItem(full), compactItem(item))) throw invalidContinuation();
+      assertHardResultConstraints(full, constraints);
+      return full;
+    }));
+    if (detail !== "full") continue;
+    for (const item of hydrated) {
+      outputBytes += encoder.encode(JSON.stringify(item)).length;
+      if (outputBytes > TOOL_SEARCH_PAGE_BYTES) {
+        throw new TBError("rate_limited", "federated search page exceeds response byte budget", {
+          retryable: false
+        });
+      }
+      output.push(item);
+    }
+  }
+  return detail === "full" ? { ...visiblePage, items: output } : visiblePage;
+}
+function pageWithCursor(page, cursor) {
+  return cursor === void 0 ? page : { ...page, cursor };
+}
+function assertPageBytes(page) {
+  if (new TextEncoder().encode(JSON.stringify(page)).length > TOOL_SEARCH_PAGE_BYTES) {
+    throw new TBError("rate_limited", "federated search page exceeds response byte budget", {
+      retryable: false
+    });
+  }
+}
+async function executeFederatedSearch(deps, input) {
+  if (deps.remote.instanceId === void 0 || input.state.compareAndSwap === void 0) {
+    throw new TBError(
+      "invalid_argument",
+      "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 },
+    matching: wireOpts.matching ?? "best",
+    ...wireOpts.minCoverage === void 0 ? {} : { minCoverage: wireOpts.minCoverage },
+    ...wireOpts.pathPrefix === void 0 ? {} : { pathPrefix: wireOpts.pathPrefix }
+  });
+  input = {
+    ...input,
+    request: {
+      query: input.request.query,
+      opts: {
+        ...wireOpts,
+        ...constraints.effects === void 0 ? {} : { effects: constraints.effects },
+        matching: constraints.matching,
+        ...constraints.minCoverage === void 0 ? {} : { minCoverage: constraints.minCoverage },
+        ...constraints.pathPrefix === void 0 ? {} : { pathPrefix: constraints.pathPrefix }
+      }
+    }
+  };
+  const viaError = checkVia(
+    parseVia(input.headers.get(HEADER_VIA) ?? void 0),
+    deps.remote.instanceId,
+    deps.remote.maxHops
+  );
+  if (viaError !== null) throw viaError;
+  const settings = federatedSearchSettings(deps.remote);
+  await input.searchSync?.ensureReady();
+  if (input.search.revision === void 0) {
+    throw new TBError("invalid_argument", "recursive search requires a revisioned search index");
+  }
+  const localRevision = await input.search.revision();
+  const deadlineMs = clampHeader(input.headers.get(HEADER_REMAINING_MS), settings.totalDeadlineMs);
+  const sessionTtlMs = clampHeader(input.headers.get(HEADER_SESSION_TTL_MS), settings.sessionTtlMs);
+  const sourceBudget = clampHeader(input.headers.get(HEADER_SOURCE_BUDGET), settings.maxSources);
+  const deadline = Date.now() + deadlineMs;
+  const expiresAtMs = Date.now() + sessionTtlMs;
+  const limit = input.request.opts?.limit ?? 10;
+  const requestDigest = await sha256Hex(canonicalJson({
+    authorization: input.ctx.scopes,
+    request: requestForDigest(input.request, limit)
+  }));
+  const sessionStore = new FederatedSearchSessionStore(input.state);
+  const plan = prepareToolSearchQuery(input.request.query);
+  const registry = new NodeRegistryStore(input.state);
+  const snapshot = await registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
+  const allDirect = directRemoteNodes(snapshot.items);
+  const eligibleRemotes = allDirect.filter((node) => {
+    const relation = childPrefixFor(node.path, input.request.opts?.pathPrefix);
+    return relation.eligible && check(input.ctx, node.path, "read").allow && check(input.ctx, node.path, "call").allow;
+  });
+  const includeLocal = localEligible(allDirect, input.request.opts?.pathPrefix);
+  const configuredRemotes = eligibleRemotes.filter((node) => node.config?.kind === "remote" && node.config.skRef !== void 0);
+  const secretAvailability = await mapLimit(
+    configuredRemotes,
+    settings.maxConcurrency,
+    async (node) => {
+      if (node.config?.kind !== "remote" || node.config.skRef === void 0) return false;
+      try {
+        return await deps.secrets.resolve(node.config.skRef) !== void 0;
+      } catch {
+        return false;
+      }
+    }
+  );
+  const participatingRemotes = configuredRemotes.filter((_node, index) => secretAvailability[index] === true);
+  const unavailableRemotes = configuredRemotes.filter((_node, index) => secretAvailability[index] !== true);
+  const transportSettings = await resolveRemoteSettings(input.state, deps.remote);
+  const topologyNodes = snapshot.items.filter((node) => check(input.ctx, node.path, "read").allow && check(input.ctx, node.path, "call").allow);
+  const digest = await topologyDigest(topologyNodes, includeLocal, localRevision, {
+    allowInsecure: transportSettings.allowInsecure,
+    allowlist: [...transportSettings.allowlist].sort(),
+    availableRemotes: participatingRemotes.map((node) => node.path),
+    instanceId: transportSettings.instanceId ?? null,
+    maxHops: transportSettings.maxHops
+  });
+  const remoteNodes = new Map(participatingRemotes.map((node) => [node.path, node]));
+  const cursor = input.request.opts?.cursor;
+  if (cursor !== void 0) {
+    const current = await sessionStore.read(cursor, { actorKeyId: input.ctx.keyId, requestDigest });
+    if (current.topologyDigest !== digest || current.rankingVersion !== TOOL_SEARCH_RANKING_VERSION) {
+      throw invalidContinuation();
+    }
+    if (input.headers.get(HEADER_VALIDATE_SNAPSHOT) === "1") {
+      await validateSourceSnapshots(
+        deps,
+        input,
+        current.sourceContinuations,
+        remoteNodes,
+        deadline,
+        Date.parse(current.expiresAt),
+        settings.maxConcurrency
+      );
+      return { items: [] };
+    }
+    if (current.nextHandle === null) throw invalidContinuation();
+    let next;
+    try {
+      next = await sessionStore.read(current.nextHandle, {
+        actorKeyId: input.ctx.keyId,
+        requestDigest
+      });
+    } catch (error) {
+      if (!(error instanceof TBError) || error.code !== "invalid_argument") throw error;
+    }
+    if (next !== void 0) assertNextRecord(current, next, digest);
+    const cachedNext = next !== void 0;
+    if (next === void 0) {
+      const state2 = await computePage(
+        deps,
+        input,
+        structuredClone(current.sourceContinuations),
+        remoteNodes,
+        deadline,
+        Date.parse(current.expiresAt),
+        plan.totalTermCount,
+        false,
+        current.excludedStatuses,
+        settings.maxConcurrency
+      );
+      const hasMore2 = responseHasMore(state2.sources);
+      const nextNextHandle = hasMore2 ? sessionStore.issueHandle() : null;
+      next = await sessionStore.create(current.nextHandle, {
+        actorKeyId: input.ctx.keyId,
+        excludedStatuses: state2.excluded,
+        expiresAt: current.expiresAt,
+        federationPolicy: current.federationPolicy,
+        generation: current.generation + 1,
+        nextHandle: nextNextHandle,
+        page: state2.page,
+        rankingVersion: TOOL_SEARCH_RANKING_VERSION,
+        requestDigest,
+        sessionId: current.sessionId,
+        sourceContinuations: serializableSources(state2.sources),
+        topologyDigest: digest
+      });
+      assertNextRecord(current, next, digest);
+      assertCachedPage(state2, next);
+    }
+    if (cachedNext) {
+      await validateSourceSnapshots(
+        deps,
+        input,
+        next.sourceContinuations,
+        remoteNodes,
+        deadline,
+        Date.parse(next.expiresAt),
+        settings.maxConcurrency
+      );
+    }
+    const wantsSnapshot2 = input.headers.get(HEADER_WANT_SNAPSHOT) === "1";
+    const responsePage2 = {
+      ...pageWithCursor(
+        next.page,
+        next.nextHandle === null ? void 0 : current.nextHandle
+      ),
+      ...wantsSnapshot2 ? { snapshot: current.nextHandle } : {}
+    };
+    const response2 = await hydratePage(
+      deps,
+      input,
+      responsePage2,
+      next.sourceContinuations,
+      remoteNodes,
+      deadline,
+      cachedNext
+    );
+    assertPageBytes(response2);
+    return response2;
+  }
+  const initialExcluded = eligibleRemotes.filter((node) => node.config?.kind === "remote" && node.config.skRef === void 0).map((node) => ({ path: node.path, status: "unsupported" }));
+  initialExcluded.push(...unavailableRemotes.map((node) => ({
+    path: node.path,
+    status: "unavailable"
+  })));
+  const availableRemoteSlots = Math.max(0, sourceBudget - (includeLocal ? 1 : 0));
+  const selectedRemotes = participatingRemotes.slice(0, availableRemoteSlots);
+  for (const node of participatingRemotes.slice(availableRemoteSlots)) {
+    initialExcluded.push({ path: node.path, status: "budget_exhausted" });
+  }
+  if (snapshot.truncated) initialExcluded.push({ path: "", status: "budget_exhausted" });
+  const allocations = selectedRemotes.map((_node, index) => {
+    const base = selectedRemotes.length === 0 ? 0 : Math.floor(availableRemoteSlots / selectedRemotes.length);
+    const extra = index < availableRemoteSlots % Math.max(1, selectedRemotes.length) ? 1 : 0;
+    return Math.max(1, base + extra);
+  });
+  const sources = [
+    ...includeLocal ? [{ balanceCount: 0, budget: 1, done: false, kind: "local", path: "" }] : [],
+    ...selectedRemotes.map((node, index) => ({
+      balanceCount: 0,
+      budget: allocations[index] ?? 1,
+      done: false,
+      kind: "remote",
+      path: node.path
+    }))
+  ];
+  const state = await computePage(
+    deps,
+    input,
+    sources,
+    remoteNodes,
+    deadline,
+    expiresAtMs,
+    plan.totalTermCount,
+    true,
+    initialExcluded,
+    settings.maxConcurrency
+  );
+  const candidateSourceCount = (includeLocal ? 1 : 0) + eligibleRemotes.length;
+  if (candidateSourceCount > 0 && state.successfulSources === 0 && state.page.items.length === 0) {
+    throw new TBError("unavailable", "all federated search sources failed", { retryable: true });
+  }
+  const hasMore = responseHasMore(state.sources);
+  const wantsSnapshot = input.headers.get(HEADER_WANT_SNAPSHOT) === "1";
+  const needsSession = hasMore || wantsSnapshot;
+  const sessionHandle = needsSession ? sessionStore.issueHandle() : void 0;
+  const responseCursor = hasMore ? sessionHandle : void 0;
+  const nextHandle = hasMore ? sessionStore.issueHandle() : null;
+  const responsePage = {
+    ...pageWithCursor(state.page, responseCursor),
+    ...wantsSnapshot && sessionHandle !== void 0 ? { snapshot: sessionHandle } : {}
+  };
+  const response = await hydratePage(
+    deps,
+    input,
+    responsePage,
+    state.sources,
+    remoteNodes,
+    deadline
+  );
+  assertPageBytes(response);
+  if (sessionHandle !== void 0) {
+    await sessionStore.create(sessionHandle, {
+      actorKeyId: input.ctx.keyId,
+      excludedStatuses: state.excluded,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+      federationPolicy: { limit, matching: input.request.opts?.matching ?? "best" },
+      generation: 0,
+      nextHandle,
+      page: state.page,
+      rankingVersion: TOOL_SEARCH_RANKING_VERSION,
+      requestDigest,
+      sourceContinuations: serializableSources(state.sources),
+      topologyDigest: digest
+    });
+  }
+  return response;
+}
+
 // ../app/src/routes/search.ts
+function requestWithNormalizedLimit(request) {
+  return {
+    ...request,
+    opts: {
+      ...request.opts ?? {},
+      limit: normalizeToolSearchLimit(request.opts?.limit)
+    }
+  };
+}
 function registerSearchRoute(app, env) {
   const { deps, globalSearchCapabilities, searchSync } = env;
   app.post(
@@ -37610,8 +39490,7 @@ function registerSearchRoute(app, env) {
       if (body === null || typeof body !== "object" || Array.isArray(body)) {
         throw new TBError("invalid_argument", "body must be a JSON object");
       }
-      const bodyKeys = Object.keys(body);
-      if (bodyKeys.some((key) => key !== "query" && key !== "opts")) {
+      if (Object.keys(body).some((key) => key !== "query" && key !== "opts")) {
         throw new TBError("invalid_argument", "body only accepts query and opts");
       }
       if (typeof body.query !== "string" || body.query.trim().length === 0) {
@@ -37622,105 +39501,71 @@ function registerSearchRoute(app, env) {
         throw new TBError("invalid_argument", "opts must be a JSON object");
       }
       const opts = rawOpts ?? {};
-      if (Object.keys(opts).some((key) => key !== "mode" && key !== "limit" && key !== "cursor")) {
-        throw new TBError("invalid_argument", "opts only accepts mode, limit and cursor");
+      const optionKeys = /* @__PURE__ */ new Set([
+        "cursor",
+        "detail",
+        "effects",
+        "federation",
+        "limit",
+        "matching",
+        "minCoverage",
+        "mode",
+        "pathPrefix"
+      ]);
+      if (Object.keys(opts).some((key) => !optionKeys.has(key))) {
+        throw new TBError("invalid_argument", "opts contains an unknown search option");
       }
-      const mode = opts.mode ?? "keyword";
-      if (mode !== "keyword" && mode !== "semantic") {
-        throw new TBError("invalid_argument", "opts.mode must be 'keyword' or 'semantic'");
+      if (opts.cursor !== void 0 && typeof opts.cursor !== "string") {
+        throw new TBError("invalid_argument", "opts.cursor must be a string");
+      }
+      const parsed = toolSearchRequestSchema.safeParse({
+        query: body.query,
+        ...rawOpts === void 0 ? {} : { opts }
+      });
+      if (!parsed.success) {
+        throw new TBError(
+          "invalid_argument",
+          parsed.error.issues[0]?.message ?? "invalid search request"
+        );
       }
+      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 limit = normalizeToolSearchLimit(opts.limit);
-      if (opts.cursor !== void 0 && typeof opts.cursor !== "string") {
-        throw new TBError("invalid_argument", "opts.cursor must be a string");
-      }
-      const wireRequest = toolSearchRequestSchema.parse({
-        query: body.query,
-        ...rawOpts === void 0 ? {} : { opts }
-      });
-      const query = wireRequest.query;
-      await searchSync?.ensureReady();
-      const ctx = c.get("ctx");
-      const registry = new NodeRegistryStore(c.get("store"));
-      const selected = [];
-      const workLimit = Math.min(
-        TOOL_SEARCH_WORK_LIMIT,
-        Math.max(TOOL_SEARCH_BATCH_LIMIT, limit * 2)
-      );
-      let scanCursor = opts.cursor;
-      let responseCursor;
-      let responseCandidate;
-      let scanned = 0;
-      let stopped = false;
-      while (!stopped && selected.length < limit && scanned < workLimit) {
-        const batchLimit = Math.min(TOOL_SEARCH_BATCH_LIMIT, workLimit - scanned);
-        const page = await search.search(query, {
-          mode,
-          limit: batchLimit,
-          ...scanCursor === void 0 ? {} : { cursor: scanCursor }
-        });
-        if (page.items.length === 0) {
-          responseCursor = page.cursor;
-          break;
-        }
-        const nodes = await registry.getMany(page.items.map((candidate) => candidate.path));
-        for (const [index, candidate] of page.items.entries()) {
-          scanned++;
-          if (!check(ctx, candidate.path, "read").allow || !check(ctx, candidate.path, "call").allow) {
-            continue;
-          }
-          const node = nodes.get(candidate.path);
-          if (node === void 0 || node.kind !== "mcp" && node.kind !== "http" && node.kind !== "tool" || node.config?.kind !== node.kind || virtualizeTools(node.virtualize, [{ name: candidate.name }]).exposed.length === 0) {
-            continue;
-          }
-          selected.push({ candidate, node });
-          if (selected.length === limit) {
-            const hasUnscanned = index < page.items.length - 1 || page.cursor !== void 0;
-            responseCandidate = hasUnscanned ? candidate : void 0;
-            responseCursor = void 0;
-            stopped = true;
-            break;
-          }
-        }
-        if (stopped) break;
-        responseCursor = page.cursor;
-        if (page.cursor === void 0) break;
-        scanCursor = page.cursor;
-      }
-      const canonicalTools = await canonicalSearchTools(
-        c.get("store"),
-        selected.map((item) => item.node)
-      );
-      const items = [];
-      let pageBytes = 0;
-      for (const [index, selectedItem] of selected.entries()) {
-        const raw = canonicalTools.get(selectedItem.candidate.path)?.find((tool2) => tool2.name === selectedItem.candidate.name);
-        if (raw === void 0) continue;
-        const tool = virtualizeTools(selectedItem.node.virtualize, [raw]).exposed[0];
-        if (tool === void 0) continue;
-        const item = { path: selectedItem.candidate.path, tool };
-        const itemBytes = new TextEncoder().encode(JSON.stringify(item)).length;
-        if (pageBytes + itemBytes > TOOL_SEARCH_PAGE_BYTES) {
-          if (items.length === 0) {
-            throw new TBError("internal", "\u5DE5\u5177\u641C\u7D22\u9875\u9762\u5B57\u8282\u9884\u7B97\u65E0\u6CD5\u5BB9\u7EB3\u9996\u4E2A\u7ED3\u679C");
-          }
-          responseCandidate = selected[index - 1]?.candidate;
-          responseCursor = void 0;
-          break;
-        }
-        items.push(item);
-        pageBytes += itemBytes;
+      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");
+      if (federation === "recursive" && !capabilities.includes("search:federated")) {
+        throw new TBError(
+          "invalid_argument",
+          "recursive search requires capability 'search:federated'"
+        );
       }
-      if (responseCandidate !== void 0) {
-        responseCursor = await search.cursorFor(query, responseCandidate, mode);
+      if (federation === "recursive" && mode === "semantic") {
+        throw new TBError("invalid_argument", "semantic search cannot use recursive federation");
       }
-      if (items.length === 0) responseCursor = void 0;
-      const result = responseCursor === void 0 ? { items } : { items, cursor: responseCursor };
+      const normalizedRequest = {
+        ...request,
+        opts: { ...request.opts ?? {}, federation }
+      };
+      const result = federation === "local" ? await executeLocalSearch({
+        ctx: c.get("ctx"),
+        search,
+        ...searchSync === void 0 ? {} : { searchSync },
+        state: c.get("store")
+      }, normalizedRequest) : await executeFederatedSearch(deps, {
+        ctx: c.get("ctx"),
+        headers: c.req.raw.headers,
+        request: normalizedRequest,
+        requestUrl: c.req.url,
+        search,
+        ...searchSync === void 0 ? {} : { searchSync },
+        state: c.get("store")
+      });
       return new Response(JSON.stringify(toolSearchPageSchema.parse(result)), {
         headers: { "content-type": contentTypeFor("json") }
       });
@@ -37909,7 +39754,7 @@ function mcpBridgeFor(c, env, app) {
       invokePath: "/~search",
       mcpName: "tb_search",
       operation: "search",
-      description: "Search visible tools across the Tool Bridge tree.",
+      description: "Search visible tools across the Tool Bridge tree (compact by default).",
       effect: "read",
       inputSchema: {
         type: "object",
@@ -37918,7 +39763,20 @@ function mcpBridgeFor(c, env, app) {
           query: { type: "string", minLength: 1 },
           mode: { type: "string", enum: ["keyword", "semantic"] },
           limit: { type: "integer", minimum: 1, maximum: 200 },
-          cursor: { type: "string", minLength: 1 }
+          cursor: { type: "string", minLength: 1 },
+          detail: { type: "string", enum: ["compact", "full"], default: "compact" },
+          effects: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "string",
+              enum: ["read", "write", "destructive", "unknown"]
+            }
+          },
+          federation: { type: "string", enum: ["local", "recursive"] },
+          matching: { type: "string", enum: ["best", "all"] },
+          minCoverage: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+          pathPrefix: { type: "string", minLength: 1 }
         },
         required: ["query"]
       }
@@ -38126,15 +39984,27 @@ function mcpBridgeFor(c, env, app) {
         if (tool.operation === "search") {
           headers2.set("accept", "application/json");
           headers2.set("content-type", "application/json");
-          const opts = Object.fromEntries(
-            ["mode", "limit", "cursor"].filter((key) => args[key] !== void 0).map((key) => [key, args[key]])
-          );
+          const opts = {
+            detail: args.detail ?? "compact",
+            ...Object.fromEntries(
+              [
+                "mode",
+                "limit",
+                "cursor",
+                "effects",
+                "federation",
+                "matching",
+                "minCoverage",
+                "pathPrefix"
+              ].filter((key) => args[key] !== void 0).map((key) => [key, args[key]])
+            )
+          };
           const response2 = await app.request(new Request(new URL("/~search", c.req.url), {
             method: "POST",
             headers: headers2,
             body: JSON.stringify({
               query: args.query,
-              ...Object.keys(opts).length === 0 ? {} : { opts }
+              opts
             })
           }));
           return await resultFromResponse(response2);
@@ -38395,6 +40265,7 @@ async function handleInvoke(c, env) {
       deps
     );
     assertSecretRefUse(ctx.scopes, cfgPatch);
+    await assertMcpOAuthConfig(cfgPatch, deps.secrets);
     await assertContextConfig(cfgPatch, deps);
     await assertSkillhubConfig(cfgPatch, deps);
     await assertToolConfig(cfgPatch, deps, ctx, targetPath);
@@ -38490,6 +40361,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"] : []
     ];
   };
@@ -38526,8 +40398,17 @@ async function handleHelp(c, env) {
     return renderHelp(await enrichHelp(model2, "", store), rep);
   }
   if (!check(ctx, path, "read").allow) throw TBError.notFound("not found");
-  const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~help", deps);
-  if (remote) return remote;
+  const projector = await remotePathProjectorIfMatch(registry, path);
+  if (projector !== null) {
+    const headers = new Headers(c.req.raw.headers);
+    headers.set("accept", "application/json");
+    const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~help", deps, headers);
+    if (remote === null) throw remoteProtocolError("remote ~help lost its mount owner");
+    if (!remote.ok) return remote;
+    const parsed = helpJsonSchema.safeParse(await remote.json().catch(() => null));
+    if (!parsed.success) throw remoteProtocolError("remote ~help returned invalid JSON");
+    return renderHelp(projector.projectHelp(parsed.data, path, ctx), rep);
+  }
   const builtins = builtinsOf(store);
   const refresh = c.req.query("refresh") === "1";
   const schemas2 = c.req.query("schemas") === "1";
@@ -38554,18 +40435,45 @@ async function handleHelp(c, env) {
 
 // ../app/src/routes/tree.ts
 var REMOTE_OPAQUE_KINDS = /* @__PURE__ */ new Set(["remote"]);
+function renderTree(tree, rep) {
+  if (rep === "json") {
+    return new Response(JSON.stringify(treeJsonSchema.parse(tree)), {
+      headers: { "content-type": contentTypeFor("json") }
+    });
+  }
+  if (rep === "dsl") {
+    return new Response(renderTreeDsl(tree), {
+      headers: { "content-type": contentTypeFor("dsl") }
+    });
+  }
+  return new Response(`\`\`\`text
+${renderTreeDsl(tree)}\`\`\`
+`, {
+    headers: { "content-type": contentTypeFor("markdown") }
+  });
+}
 async function handleTree(c, env) {
   const { deps } = env;
   const path = splitReserved(new URL(c.req.url).pathname, "~tree");
   if (path === null) throw TBError.notFound("no such path");
   const ctx = c.get("ctx");
   const store = c.get("store");
+  const rep = negotiate(c.req.header("accept"));
   if (path !== "" && !check(ctx, path, "read").allow) throw TBError.notFound("not found");
   const registry = new NodeRegistryStore(store);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   if (path !== "") {
-    const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~tree", deps);
-    if (remote) return remote;
+    const projector = await remotePathProjectorIfMatch(registry, path);
+    if (projector !== null) {
+      const headers = new Headers(c.req.raw.headers);
+      headers.set("accept", "application/json");
+      const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~tree", deps, headers);
+      if (remote === null) throw remoteProtocolError("remote ~tree lost its mount owner");
+      if (!remote.ok) return remote;
+      const parsed = treeJsonSchema.safeParse(await remote.json().catch(() => null));
+      if (!parsed.success) throw remoteProtocolError("remote ~tree returned invalid JSON");
+      return renderTree(projector.projectTree(parsed.data, path, ctx), rep);
+    }
   }
   let rootEntry;
   if (path !== "") {
@@ -38596,22 +40504,7 @@ async function handleTree(c, env) {
     opaqueKinds: REMOTE_OPAQUE_KINDS,
     ...rootEntry !== void 0 ? { rootEntry } : {}
   });
-  const rep = negotiate(c.req.header("accept"));
-  if (rep === "json") {
-    return new Response(JSON.stringify(treeJsonSchema.parse(tree)), {
-      headers: { "content-type": contentTypeFor("json") }
-    });
-  }
-  if (rep === "dsl") {
-    return new Response(renderTreeDsl(tree), {
-      headers: { "content-type": contentTypeFor("dsl") }
-    });
-  }
-  return new Response(`\`\`\`text
-${renderTreeDsl(tree)}\`\`\`
-`, {
-    headers: { "content-type": contentTypeFor("markdown") }
-  });
+  return renderTree(tree, rep);
 }
 
 // ../app/src/tbApp.ts
@@ -39414,6 +41307,40 @@ var FsObjectStore = class {
 // ../core/src/node/shellExecutor.ts
 import { spawn as nodeSpawn } from "child_process";
 var SHELL_OUTPUT_LIMIT_BYTES = 1024 * 1024;
+var SHELL_EXEC_DEFAULT_TIMEOUT_MS = 55e3;
+
+// ../core/src/node/structuredCommand.ts
+import { spawn as nodeSpawn2 } from "child_process";
+var STRUCTURED_COMMAND_PROFILE_VERSION = 1;
+var STRUCTURED_COMMAND_MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+var envNameSchema = external_exports.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+var argumentSchema = external_exports.strictObject({
+  input: external_exports.string().min(1),
+  description: external_exports.string().min(1).optional(),
+  flag: external_exports.string().min(1).optional(),
+  choices: external_exports.array(external_exports.string()).min(1).optional(),
+  multiple: external_exports.boolean().optional(),
+  required: external_exports.boolean().optional(),
+  type: external_exports.enum(["string", "number", "boolean"]).optional()
+});
+var commandSchema = external_exports.strictObject({
+  name: external_exports.string().min(1),
+  description: external_exports.string().min(1),
+  executable: external_exports.string().min(1),
+  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"]),
+  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(),
+  inheritEnv: external_exports.array(envNameSchema).optional()
+});
+var profileSchema = external_exports.strictObject({
+  version: external_exports.literal(STRUCTURED_COMMAND_PROFILE_VERSION),
+  path: external_exports.string().min(1),
+  description: external_exports.string().min(1),
+  commands: external_exports.array(commandSchema).min(1)
+});
 
 // src/objects.ts
 import { dirname as dirname2, join as join2, sep as sep2 } from "path";
@@ -39697,7 +41624,7 @@ var PgSearchDriver = class {
       records,
       PG_SEARCH_TOOLS_TABLE,
       PG_SEARCH_TOOLS_COLUMNS,
-      (record2) => [record2.path, record2.name, record2.description, record2.feedback]
+      (record2) => [record2.path, record2.name, record2.description, record2.effect, record2.feedback]
     );
   }
   insertSnapshots(digests) {
@@ -39887,7 +41814,7 @@ var SqliteSearchDriver = class {
   }
   insertRecords(records) {
     return records.map((record2) => ({
-      params: [record2.path, record2.name, record2.description, record2.feedback],
+      params: [record2.path, record2.name, record2.description, record2.effect, record2.feedback],
       sql: TOOL_SEARCH_INSERT_SQL
     }));
   }
@@ -40031,7 +41958,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.17.0",
+  version: "0.19.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",