@tool-bridge/server 0.17.0 → 0.20.0

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

@@ -1,6 +1,6 @@
 import {
   createGuardedFetch
-} from "./chunk-U5UHT7CX.js";
+} from "./chunk-3WL6EXYX.js";
 import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
@@ -9,6 +9,7 @@ import {
   DEFAULT_STORE_DRIVER_KEY_ROOT,
   DEVICE_CALL_TIMEOUT_MS,
   DeviceGatewaySession,
+  DeviceMailboxService,
   FEEDBACK_HIDE_SCORE,
   FeedbackStore,
   HEADER_TB_CONTEXT,
@@ -40,9 +41,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,
@@ -88,6 +91,16 @@ import {
   derivePresence,
   deviceDirectoryHelpModel,
   deviceFsHelpModel,
+  deviceOperationClaimRequestSchema,
+  deviceOperationClaimResponseSchema,
+  deviceOperationCompleteRequestSchema,
+  deviceOperationDetailSchema,
+  deviceOperationIdentityRequestSchema,
+  deviceOperationListRequestSchema,
+  deviceOperationListResponseSchema,
+  deviceOperationRenewRequestSchema,
+  deviceOperationRenewResponseSchema,
+  deviceOperationSummarySchema,
   deviceShellHelpModel,
   discriminatedUnion,
   dispatchContextCmd,
@@ -124,6 +137,7 @@ import {
   normalizeEntryPath,
   normalizePath,
   normalizeToolSearchLimit,
+  normalizeToolSearchOptions,
   normalizeToolSearchPath,
   normalizeUpstreamError,
   number,
@@ -146,6 +160,7 @@ import {
   pgSearchDialect,
   pluginTokenSecretName,
   prefixUpperBound,
+  prepareToolSearchQuery,
   preprocess,
   readinessResponseSchema,
   record,
@@ -169,8 +184,11 @@ import {
   toJSONSchema,
   toolHelpModel,
   toolSearchPageSchema,
+  toolSearchRelevanceSchema,
   toolSearchRequestSchema,
   toolSearchSnapshotDigest,
+  toolSearchSourceResultSchema,
+  toolSearchSourceSchema,
   toolsToHelpModel,
   treeJsonSchema,
   union,
@@ -178,7 +196,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-RVWZN3CI.js";
+} from "./chunk-WIGQCP6O.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -1545,12 +1563,12 @@ function requireDevice(deps) {
   }
   return deps.device;
 }
-async function invokeDevice(deps, deviceId, req) {
+async function attemptDevice(deps, deviceId, req) {
   const id = crypto.randomUUID();
   const upload = req.context === void 0 ? null : await issueDeviceCallUpload(deps, deviceId, id, req.context);
-  let body;
+  let attempt2;
   try {
-    body = await requireDevice(deps).invoke(deviceId, {
+    attempt2 = await requireDevice(deps).invoke(deviceId, {
       id,
       path: req.path,
       arguments: req.arguments,
@@ -1560,11 +1578,15 @@ async function invokeDevice(deps, deviceId, req) {
     await upload?.revoke().catch(() => {
     });
   }
-  if (!body || !("ok" in body)) {
+  if (attempt2 === null || typeof attempt2 !== "object" || !["completed", "not_dispatched", "unknown"].includes(attempt2.disposition) || attempt2.result === null || typeof attempt2.result !== "object" || !("ok" in attempt2.result) || attempt2.disposition !== "completed" && attempt2.result.ok !== false) {
     throw new TBError("unavailable", "device session returned invalid result");
   }
-  if (body.ok) return body.value;
-  throw tbErrorFromBody(body.error);
+  return attempt2;
+}
+async function invokeDevice(deps, deviceId, req) {
+  const attempt2 = await attemptDevice(deps, deviceId, req);
+  if (attempt2.result.ok) return attempt2.result.value;
+  throw tbErrorFromBody(attempt2.result.error);
 }
 function deviceCallContextFrom(ctx) {
   const now = Date.now();
@@ -10023,13 +10045,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 +10060,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 +19210,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 +19286,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 +19313,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 +19346,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 +19408,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 +19431,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 +19460,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 +19475,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 +19490,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 +19511,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 +19588,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 +19728,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 } : {}
         })
       };
     }
@@ -20509,7 +20648,7 @@ async function processDeviceHello(opts) {
         input,
         authCtx.keyId,
         now,
-        input.path === mountPath ? { online: true, lastSeenAt: now } : {}
+        input.path === mountPath ? { deviceId: hello.deviceId, online: true, lastSeenAt: now } : {}
       );
     } catch (error) {
       await searchSync?.abort(marker);
@@ -20523,6 +20662,64 @@ async function processDeviceHello(opts) {
   return { mountPath, keyId: authCtx.keyId, searchIndexed };
 }
 
+// ../app/src/deviceMailbox.ts
+var KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS = "sys:device-mailbox-cleanup-progress:v1";
+function positiveInt2(value, fallback, field) {
+  const actual = value ?? fallback;
+  if (!Number.isSafeInteger(actual) || actual < 1) {
+    throw new TBError("invalid_argument", `${field} must be a positive integer`);
+  }
+  return actual;
+}
+function parseProgress(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || typeof value.cursor !== "string" || !Number.isSafeInteger(value.revision) || value.revision < 1) throw new TBError("internal", "device mailbox cleanup progress is invalid");
+  return value;
+}
+function createDeviceMailboxService(deps) {
+  return new DeviceMailboxService(deps.state, deps.encryptionKey);
+}
+async function cleanupDeviceMailbox(deps, opts = {}) {
+  await deps.ensureReady?.();
+  if (deps.state.compareAndSwap === void 0) {
+    throw new TBError("unavailable", "device mailbox cleanup requires StateStore.compareAndSwap");
+  }
+  const mailbox = createDeviceMailboxService(deps);
+  const maxPages = Math.min(positiveInt2(opts.maxPages, 8, "maxPages"), 64);
+  const limit = Math.min(positiveInt2(opts.limit, 200, "limit"), 200);
+  const raw = await deps.state.get(KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS);
+  let progress = raw === null ? null : parseProgress(raw);
+  let cursor = progress?.cursor;
+  const aggregate = { deleted: 0, expired: 0, scanned: 0 };
+  for (let pageNumber = 0; pageNumber < maxPages; pageNumber++) {
+    const page = await mailbox.cleanup({ limit, ...cursor === void 0 ? {} : { cursor } });
+    aggregate.deleted += page.deleted;
+    aggregate.expired += page.expired;
+    aggregate.scanned += page.scanned;
+    if (page.cursor === void 0) {
+      if (progress !== null) {
+        await deps.state.compareAndSwap(
+          KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS,
+          progress.revision,
+          null
+        );
+      }
+      return aggregate;
+    }
+    const next = {
+      cursor: page.cursor,
+      revision: (progress?.revision ?? 0) + 1
+    };
+    if (!await deps.state.compareAndSwap(
+      KEY_DEVICE_MAILBOX_CLEANUP_PROGRESS,
+      progress?.revision ?? null,
+      next
+    )) return aggregate;
+    progress = next;
+    cursor = next.cursor;
+  }
+  return { ...aggregate, ...cursor === void 0 ? {} : { cursor } };
+}
+
 // ../../node_modules/.pnpm/@modelcontextprotocol+server@2.0.0/node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
 var __create2 = Object.create;
 var __defProp2 = Object.defineProperty;
@@ -28157,13 +28354,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 +28369,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("");
@@ -36168,17 +36365,34 @@ function assertSchemaShape(value, path, depth = 0) {
     list.forEach((sub, i) => assertSchemaShape(sub, `${path}/${key}/${i}`, depth + 1));
   }
 }
-function inputSchemaOf(raw) {
-  if (raw === void 0) return { type: "object", properties: {} };
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+function inputSchemaOf(raw, delivery) {
+  if (raw === void 0 && delivery === void 0) return { type: "object", properties: {} };
+  const source = raw ?? { type: "object", properties: {} };
+  if (source === null || typeof source !== "object" || Array.isArray(source)) {
     throw new Error("MCP tool inputSchema must be a JSON Schema object");
   }
-  const schema = raw;
+  const schema = source;
   if (schema.type !== void 0 && schema.type !== "object") {
     throw new Error("MCP tool inputSchema root type must be object");
   }
   assertSchemaShape(schema, "inputSchema");
-  return { ...schema, type: "object" };
+  if (delivery !== "mailbox" && delivery !== "both") {
+    return { ...schema, type: "object" };
+  }
+  const properties = schema.properties;
+  if (properties !== void 0 && (properties === null || typeof properties !== "object" || Array.isArray(properties))) throw new Error("MCP tool inputSchema properties must be an object");
+  return {
+    ...schema,
+    type: "object",
+    properties: {
+      ...properties ?? {},
+      "~delivery": {
+        type: "string",
+        enum: delivery === "both" ? ["realtime", "mailbox", "fallback"] : ["mailbox", "fallback"],
+        description: "Tool Bridge delivery policy; fallback prefers realtime and queues only when dispatch definitely did not occur."
+      }
+    }
+  };
 }
 function annotationsOf(tool) {
   const annotations = {};
@@ -36204,7 +36418,7 @@ async function projectTools(source, validator) {
 HTBP ${bridge.invokePath}`;
       let inputSchema;
       try {
-        inputSchema = inputSchemaOf(bridge.inputSchema);
+        inputSchema = inputSchemaOf(bridge.inputSchema, bridge.delivery);
       } catch {
         throw new ProtocolError3(
           ProtocolErrorCode2.InternalError,
@@ -36350,6 +36564,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 +36697,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 +36728,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 +36765,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
@@ -36438,6 +36796,16 @@ import { Hono } from "hono";
 // ../core/src/protocol/openapi.ts
 var schemaRegistry = external_exports.registry();
 var schemas = {
+  DeviceOperationClaimRequest: deviceOperationClaimRequestSchema,
+  DeviceOperationClaimResponse: deviceOperationClaimResponseSchema,
+  DeviceOperationCompleteRequest: deviceOperationCompleteRequestSchema,
+  DeviceOperationDetail: deviceOperationDetailSchema,
+  DeviceOperationIdentityRequest: deviceOperationIdentityRequestSchema,
+  DeviceOperationListRequest: deviceOperationListRequestSchema,
+  DeviceOperationListResponse: deviceOperationListResponseSchema,
+  DeviceOperationRenewRequest: deviceOperationRenewRequestSchema,
+  DeviceOperationRenewResponse: deviceOperationRenewResponseSchema,
+  DeviceOperationSummary: deviceOperationSummarySchema,
   Error: tbErrorBodySchema,
   FeedbackDetail: feedbackDetailSchema,
   FeedbackList: feedbackListSchema,
@@ -36454,8 +36822,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 });
@@ -36670,20 +37041,82 @@ var fixedControlPlaneOpenApi = {
         "x-tool-bridge-greedy-path": true
       }
     },
+    "/~device/operations/get": {
+      post: {
+        operationId: "getDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationIdentityRequest") },
+        responses: { 200: jsonResponse("Device operation detail", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
+    "/~device/operations/list": {
+      post: {
+        operationId: "listDeviceOperations",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationListRequest") },
+        responses: { 200: jsonResponse("Visible device operation page", "DeviceOperationListResponse"), ...errorResponses }
+      }
+    },
+    "/~device/operations/cancel": {
+      post: {
+        operationId: "cancelDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationIdentityRequest") },
+        responses: { 200: jsonResponse("Cancelled or cancellation-requested operation", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/claim": {
+      post: {
+        operationId: "claimDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationClaimRequest") },
+        responses: { 200: jsonResponse("Claimed operation or next scan cursor", "DeviceOperationClaimResponse"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/renew": {
+      post: {
+        operationId: "renewDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationRenewRequest") },
+        responses: { 200: jsonResponse("Renewed operation lease", "DeviceOperationRenewResponse"), ...errorResponses }
+      }
+    },
+    "/~device/mailbox/complete": {
+      post: {
+        operationId: "completeDeviceOperation",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("DeviceOperationCompleteRequest") },
+        responses: { 200: jsonResponse("Terminal device operation", "DeviceOperationDetail"), ...errorResponses }
+      }
+    },
     "/{commandPath}": {
       post: {
         "operationId": "invoke",
         "security": bearerSecurity,
-        "parameters": [{
-          in: "path",
-          name: "commandPath",
-          required: true,
-          schema: { type: "string" },
-          description: "Complete HTBP command path, including the command/tool leaf."
-        }],
+        "parameters": [
+          {
+            in: "path",
+            name: "commandPath",
+            required: true,
+            schema: { type: "string" },
+            description: "Complete HTBP command path, including the command/tool leaf."
+          },
+          {
+            in: "query",
+            name: "ttlSeconds",
+            schema: { type: "integer", minimum: 1 },
+            description: "Mailbox operation TTL; used only when ~delivery can enqueue."
+          },
+          {
+            in: "header",
+            name: "x-tb-idempotency-key",
+            schema: { type: "string", minLength: 1, maxLength: 255 },
+            description: "Mailbox retry key; used only when ~delivery can enqueue."
+          }
+        ],
         "requestBody": {
           required: true,
-          description: "Raw command arguments; there is no {tool, arguments} envelope.",
+          description: "Raw command arguments plus the reserved optional ~delivery control.",
           content: { "application/json": { schema: {} } }
         },
         "responses": {
@@ -36694,6 +37127,7 @@ var fixedControlPlaneOpenApi = {
               "text/markdown": { schema: { type: "string" } }
             }
           },
+          202: jsonResponse("Durably accepted device operation", "DeviceOperationDetail"),
           ...errorResponses
         },
         "x-tool-bridge-greedy-path": true
@@ -36886,6 +37320,239 @@ async function handleFeedbackDelete(c, env) {
   return feedbackJson(feedbackRemoveResponseSchema, { ok: true });
 }
 
+// ../app/src/routes/deviceMailbox.ts
+var DEVICE_MAILBOX_IDEMPOTENCY_HEADER = "x-tb-idempotency-key";
+var DEVICE_MAILBOX_HTTP_BODY_BYTES = 272 * 1024;
+var DEVICE_MAILBOX_LIST_LIMIT_DEFAULT = 50;
+var DEVICE_MAILBOX_LIST_LIMIT_MAX = 200;
+function invalidRequest(message) {
+  return new TBError("invalid_argument", message);
+}
+async function mailboxJsonObject(c, opts = {}) {
+  const declaredLength = Number(c.req.header("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > DEVICE_MAILBOX_HTTP_BODY_BYTES) {
+    throw new TBError("rate_limited", "device mailbox request body is too large", {
+      retryable: false
+    });
+  }
+  const reader = c.req.raw.body?.getReader();
+  let raw = "";
+  if (reader !== void 0) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+    let received = 0;
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        received += chunk.value.byteLength;
+        if (received > DEVICE_MAILBOX_HTTP_BODY_BYTES) {
+          await reader.cancel().catch(() => {
+          });
+          throw new TBError("rate_limited", "device mailbox request body is too large", {
+            retryable: false
+          });
+        }
+        raw += decoder.decode(chunk.value, { stream: true });
+      }
+      raw += decoder.decode();
+    } catch (cause) {
+      if (cause instanceof TBError) throw cause;
+      throw invalidRequest("body must be valid UTF-8 JSON");
+    }
+  }
+  let parsed = opts.allowEmpty === true && raw === "" ? {} : null;
+  if (raw !== "") {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = null;
+    }
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw invalidRequest("body must be a JSON object");
+  }
+  return parsed;
+}
+function parseBody(schema, body) {
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) throw invalidRequest(parsed.error.issues[0]?.message ?? "invalid request");
+  return parsed.data;
+}
+function deviceOperationTtlSeconds(url2) {
+  for (const key of url2.searchParams.keys()) {
+    if (key !== "ttlSeconds") throw invalidRequest(`unknown enqueue query parameter '${key}'`);
+  }
+  const value = url2.searchParams.get("ttlSeconds");
+  if (value === null) return void 0;
+  if (!/^[1-9]\d*$/.test(value)) throw invalidRequest("ttlSeconds must be a positive integer");
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw invalidRequest("ttlSeconds must be a safe integer");
+  return parsed;
+}
+function canManage(ctx, operation) {
+  return ctx.owner === operation.caller.owner || check(ctx, operation.targetPath, "admin").allow;
+}
+function assertCanManage(ctx, operation) {
+  if (!canManage(ctx, operation)) throw TBError.notFound("device operation not found");
+}
+async function assertCurrentDeviceCredential(c, target) {
+  const ctx = c.get("ctx");
+  if (ctx.keyId !== target.deviceKeyId) {
+    throw new TBError("permission_denied", "device credential does not own this operation");
+  }
+  let existing = null;
+  try {
+    existing = await new NodeRegistryStore(c.get("store")).get(target.mountPath);
+  } catch {
+    existing = null;
+  }
+  const allowed = checkRegisterPath({
+    action: "write",
+    existing,
+    sk: {
+      id: ctx.keyId,
+      scopes: ctx.scopes,
+      ...ctx.registerPaths === void 0 ? {} : { registerPaths: ctx.registerPaths }
+    },
+    targetPath: target.mountPath
+  });
+  if (!allowed.allow) throw allowed.error;
+}
+async function enqueueDeviceCommand(c, env, input) {
+  const { arguments: args, command, marker, node } = input;
+  const ctx = c.get("ctx");
+  const result = await env.mailbox().enqueue({
+    arguments: args,
+    caller: { keyId: ctx.keyId, owner: ctx.owner },
+    deviceId: marker.deviceId,
+    deviceKeyId: node.registeredBy,
+    mountPath: marker.mountPath,
+    // 管理面与审计链必须能区分同一 tool 节点下的不同命令；权限仍按前缀 scope 判定。
+    targetPath: `${node.path}/${command}`,
+    path: `${relativeDevicePath(node.path, marker.mountPath)}/${command}`,
+    traceId: ctx.traceId,
+    ...c.req.header(DEVICE_MAILBOX_IDEMPOTENCY_HEADER) === void 0 ? {} : { idempotencyKey: c.req.header(DEVICE_MAILBOX_IDEMPOTENCY_HEADER) },
+    ...input.ttlSeconds === void 0 ? {} : { ttlSeconds: input.ttlSeconds }
+  });
+  const response = c.json(deviceOperationDetailSchema.parse(result), 202);
+  response.headers.set("x-tb-delivery", "mailbox");
+  return response;
+}
+async function handleDeviceMailboxControl(c, env) {
+  const path = new URL(c.req.url).pathname.replace(/\/+$/, "");
+  const body = await mailboxJsonObject(c);
+  const mailbox = env.mailbox();
+  const ctx = c.get("ctx");
+  if (path === "/~device/operations/get") {
+    const input = parseBody(deviceOperationIdentityRequestSchema, body);
+    const result = await mailbox.get(input.deviceId, input.operationId);
+    assertCanManage(ctx, result);
+    return c.json(deviceOperationDetailSchema.parse(result));
+  }
+  if (path === "/~device/operations/list") {
+    const input = parseBody(deviceOperationListRequestSchema, body);
+    const limit = Math.min(
+      input.opts?.limit ?? DEVICE_MAILBOX_LIST_LIMIT_DEFAULT,
+      DEVICE_MAILBOX_LIST_LIMIT_MAX
+    );
+    let cursor = input.opts?.cursor;
+    const items = [];
+    while (items.length < limit) {
+      const previous = cursor;
+      const page = await mailbox.list({
+        deviceId: input.deviceId,
+        limit: limit - items.length,
+        ...cursor === void 0 ? {} : { cursor },
+        ...input.opts?.states === void 0 ? {} : { states: input.opts.states }
+      });
+      items.push(...page.items.filter((item) => canManage(ctx, item)));
+      cursor = page.cursor;
+      if (cursor === void 0) {
+        return c.json(deviceOperationListResponseSchema.parse({ items }));
+      }
+      if (cursor === previous) {
+        throw new TBError("internal", "device mailbox list cursor did not advance");
+      }
+    }
+    const resumeCursor = cursor;
+    if (resumeCursor === void 0) {
+      return c.json(deviceOperationListResponseSchema.parse({ items }));
+    }
+    let probeCursor = resumeCursor;
+    while (probeCursor !== void 0) {
+      const previous = probeCursor;
+      const page = await mailbox.list({
+        deviceId: input.deviceId,
+        cursor: probeCursor,
+        limit: DEVICE_MAILBOX_LIST_LIMIT_MAX,
+        ...input.opts?.states === void 0 ? {} : { states: input.opts.states }
+      });
+      if (page.items.some((item) => canManage(ctx, item))) {
+        return c.json(deviceOperationListResponseSchema.parse({ items, cursor: resumeCursor }));
+      }
+      probeCursor = page.cursor;
+      if (probeCursor === previous) {
+        throw new TBError("internal", "device mailbox list cursor did not advance");
+      }
+    }
+    return c.json(deviceOperationListResponseSchema.parse({ items }));
+  }
+  if (path === "/~device/operations/cancel") {
+    const input = parseBody(deviceOperationIdentityRequestSchema, body);
+    const current = await mailbox.get(input.deviceId, input.operationId);
+    assertCanManage(ctx, current);
+    return c.json(deviceOperationDetailSchema.parse(
+      await mailbox.cancel(input.deviceId, input.operationId)
+    ));
+  }
+  throw TBError.notFound("no such path");
+}
+async function handleDeviceMailboxData(c, env) {
+  const path = new URL(c.req.url).pathname.replace(/\/+$/, "");
+  const body = await mailboxJsonObject(c);
+  const mailbox = env.mailbox();
+  const ctx = c.get("ctx");
+  const authorize = async (target) => await assertCurrentDeviceCredential(c, target);
+  if (path === "/~device/mailbox/claim") {
+    const input = parseBody(deviceOperationClaimRequestSchema, body);
+    return c.json(deviceOperationClaimResponseSchema.parse(await mailbox.claim({
+      ...input,
+      deviceKeyId: ctx.keyId,
+      authorize
+    })));
+  }
+  if (path === "/~device/mailbox/renew") {
+    const input = parseBody(deviceOperationRenewRequestSchema, body);
+    return c.json(deviceOperationRenewResponseSchema.parse(await mailbox.renew({
+      ...input,
+      deviceKeyId: ctx.keyId,
+      authorize
+    })));
+  }
+  if (path === "/~device/mailbox/complete") {
+    const input = parseBody(deviceOperationCompleteRequestSchema, body);
+    let completion;
+    if (input.outcome === "succeeded") {
+      completion = { outcome: "succeeded", result: input.result };
+    } else if (input.outcome === "result_unknown") {
+      completion = {
+        outcome: "result_unknown",
+        ...input.error === void 0 ? {} : { error: input.error }
+      };
+    } else {
+      completion = { outcome: input.outcome, error: input.error };
+    }
+    return c.json(deviceOperationDetailSchema.parse(await mailbox.complete({
+      deviceId: input.deviceId,
+      operationId: input.operationId,
+      leaseId: input.leaseId,
+      deviceKeyId: ctx.keyId,
+      authorize
+    }, completion)));
+  }
+  throw TBError.notFound("no such path");
+}
+
 // ../app/src/responses.ts
 function tbErrorResponse(err) {
   return new Response(JSON.stringify(tbErrorBodySchema.parse(err.toJSON())), {
@@ -36980,6 +37647,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 +37655,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 +37682,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 +37802,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 +37820,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 +37848,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 +37929,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 +37996,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 +38342,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 +38373,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 +39886,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 +39897,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") }
       });
@@ -37866,6 +40107,7 @@ var mcpCommand = (nodePath, nodeDescription, command) => {
     invokePath,
     description: command.h ?? nodeDescription,
     ...command.inputSchema !== void 0 ? { inputSchema: command.inputSchema } : {},
+    ...command.delivery !== void 0 ? { delivery: command.delivery } : {},
     ...command.effect !== void 0 ? { effect: command.effect } : {},
     ...command.confirm === true ? { confirm: true } : {}
   };
@@ -37880,6 +40122,7 @@ var toolSpecCommand = (node, tool, providerBacked = false) => {
     ...providerBacked ? { providerBacked: true } : {},
     description: tool.description ?? node.description,
     ...tool.inputSchema !== void 0 ? { inputSchema: tool.inputSchema } : {},
+    ...tool.delivery !== void 0 ? { delivery: tool.delivery } : {},
     ...tool.effect !== void 0 ? { effect: tool.effect } : {},
     ...tool.confirm === true ? { confirm: true } : {}
   };
@@ -37909,7 +40152,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 +40161,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 +40382,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);
@@ -38178,11 +40446,11 @@ function mcpBridgeFor(c, env, app) {
         const provider = await providerFor(node, ctx, deps);
         const raw = await upstreamTools(node, provider, deps, false, (/* @__PURE__ */ new Date()).toISOString());
         const upstreamName = resolveUpstreamTool(node.virtualize, raw, tool.toolName);
-        const result = await provider.call(upstreamName, args);
+        const result2 = await provider.call(upstreamName, args);
         return {
-          content: result.contentBlocks ?? result.content,
-          ...result.isError === true ? { isError: true } : {},
-          ...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+          content: result2.contentBlocks ?? result2.content,
+          ...result2.isError === true ? { isError: true } : {},
+          ...result2.structuredContent !== void 0 ? { structuredContent: result2.structuredContent } : {}
         };
       }
       const url2 = new URL(tool.invokePath, c.req.url);
@@ -38194,7 +40462,13 @@ function mcpBridgeFor(c, env, app) {
       const response = await app.request(
         new Request(url2, { method: "POST", headers, body: JSON.stringify(args) })
       );
-      return await resultFromResponse(response);
+      const result = await resultFromResponse(response);
+      if (args["~delivery"] !== void 0 && response.ok) {
+        return {
+          content: response.status === 202 ? { delivery: "mailbox", operation: result.content } : { delivery: "realtime", result: result.content }
+        };
+      }
+      return result;
     }
   };
 }
@@ -38229,26 +40503,102 @@ async function handleInvoke(c, env) {
   const node = resolved.node;
   const command = resolved.rest;
   if (!check(ctx, node.path, "read").allow) throw TBError.notFound("not found");
+  const toolMarker = deviceToolMarker(node);
+  let invokeRequest;
+  const readInvokeRequest = async () => {
+    if (invokeRequest !== void 0) return await invokeRequest;
+    invokeRequest = (async () => {
+      const parsed = toolMarker === null ? await c.req.json().catch(() => null) : await mailboxJsonObject(c, { allowEmpty: true });
+      if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
+        throw new TBError("invalid_argument", "body must be a JSON object (command arguments)");
+      }
+      const raw2 = { ...parsed ?? {} };
+      const unknownControls = Object.keys(raw2).filter(
+        (key) => key.startsWith("~") && key !== "~delivery"
+      );
+      if (unknownControls.length > 0) {
+        throw new TBError(
+          "invalid_argument",
+          `unknown invocation control '${unknownControls[0]}'`
+        );
+      }
+      const rawDelivery = raw2["~delivery"];
+      delete raw2["~delivery"];
+      if (rawDelivery !== void 0 && rawDelivery !== "realtime" && rawDelivery !== "mailbox" && rawDelivery !== "fallback") {
+        throw new TBError(
+          "invalid_argument",
+          "'~delivery' must be one of realtime, mailbox, fallback"
+        );
+      }
+      return {
+        arguments: raw2,
+        delivery: rawDelivery ?? "realtime",
+        explicitDelivery: rawDelivery !== void 0
+      };
+    })();
+    return await invokeRequest;
+  };
   const readInvokeBody = async () => {
-    const parsed = await c.req.json().catch(() => null);
-    if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
-      throw new TBError("invalid_argument", "body must be a JSON object (command arguments)");
+    const request = await readInvokeRequest();
+    if (request.explicitDelivery) {
+      throw new TBError(
+        "invalid_argument",
+        "'~delivery' is only supported by device-backed tool commands"
+      );
     }
-    return parsed ?? {};
+    return request.arguments;
   };
-  const toolMarker = deviceToolMarker(node);
   if (toolMarker !== null) {
     if (!check(ctx, node.path, "call").allow) {
       throw new TBError("permission_denied", `no scope grants 'call' on '${node.path}'`);
     }
-    const args2 = await readInvokeBody();
-    const result2 = await invokeDevice(deps, toolMarker.deviceId, {
+    const declared = toolMarker.cmds?.find((item) => item.name.toLowerCase() === command);
+    if (toolMarker.cmds !== void 0 && declared === void 0) throw TBError.notFound("not found");
+    const request = await readInvokeRequest();
+    const capability = declared?.delivery ?? "realtime";
+    const canRealtime = capability === "realtime" || capability === "both";
+    const canMailbox = capability === "mailbox" || capability === "both";
+    if (request.delivery === "realtime" && !canRealtime) {
+      throw new TBError("invalid_argument", "device command does not support realtime delivery");
+    }
+    if (request.delivery === "mailbox" && !canMailbox) {
+      throw new TBError("invalid_argument", "device command does not support mailbox delivery");
+    }
+    if (request.delivery === "fallback" && !canMailbox) {
+      throw new TBError("invalid_argument", "device command does not support mailbox fallback");
+    }
+    const ttlSeconds = request.delivery === "realtime" ? void 0 : deviceOperationTtlSeconds(new URL(c.req.url));
+    const enqueue = async () => await enqueueDeviceCommand(c, env, {
+      arguments: request.arguments,
+      command,
+      marker: toolMarker,
+      node,
+      ...ttlSeconds === void 0 ? {} : { ttlSeconds }
+    });
+    if (request.delivery === "mailbox" || !canRealtime) return await enqueue();
+    if (request.delivery === "fallback" && deps.device === void 0) return await enqueue();
+    const attempt2 = await attemptDevice(deps, toolMarker.deviceId, {
       // 帧 path 含命令叶子段:<mount 相对路径>/<命令>。
       path: `${relativeDevicePath(node.path, toolMarker.mountPath)}/${command}`,
-      arguments: args2,
+      arguments: request.arguments,
       context: deviceCallContextFrom(ctx)
     });
-    return renderResult(result2, negotiate(c.req.header("accept")));
+    if (attempt2.disposition === "not_dispatched" && request.delivery === "fallback") {
+      return await enqueue();
+    }
+    if (attempt2.result.ok) {
+      const response = renderResult(attempt2.result.value, negotiate(c.req.header("accept")));
+      response.headers.set("x-tb-delivery", "realtime");
+      return response;
+    }
+    if (attempt2.disposition === "unknown" && request.delivery === "fallback") {
+      throw new TBError(
+        attempt2.result.error.code,
+        `${attempt2.result.error.message}; delivery outcome is unknown and was not enqueued`,
+        { retryable: false }
+      );
+    }
+    throw tbErrorFromBody(attempt2.result.error);
   }
   if ((node.kind === "mcp" || node.kind === "http" || node.kind === "tool") && node.config !== void 0) {
     if (!check(ctx, node.path, "call").allow) {
@@ -38395,6 +40745,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 +40841,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"] : []
     ];
   };
@@ -38500,7 +40852,12 @@ function createRouteEnv(deps) {
     catalogDigest ??= catalogSetDigest(catalog);
     return catalogDigest;
   };
-  return { builtinsOf, deps, globalSearchCapabilities, pluginCatalogDigest, searchSync };
+  let mailboxInstance;
+  const mailbox = () => {
+    mailboxInstance ??= createDeviceMailboxService(deps);
+    return mailboxInstance;
+  };
+  return { builtinsOf, deps, globalSearchCapabilities, mailbox, pluginCatalogDigest, searchSync };
 }
 
 // ../app/src/routes/help.ts
@@ -38526,8 +40883,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 +40920,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 +40989,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
@@ -38683,6 +41061,13 @@ function createTbApp(deps) {
     async (c) => await runHandler(async () => {
       const segs = new URL(c.req.url).pathname.replace(/\/+$/, "").split("/");
       const last = segs.pop() ?? "";
+      const pathname = new URL(c.req.url).pathname.replace(/\/+$/, "");
+      if (pathname.startsWith("/~device/operations/")) {
+        return await handleDeviceMailboxControl(c, env);
+      }
+      if (pathname.startsWith("/~device/mailbox/")) {
+        return await handleDeviceMailboxData(c, env);
+      }
       if (last === "~register") return await handleRegister(c, env);
       if (last === "~authorize") return await handleAuthorize(c, env);
       if (last === "~feedback" || segs[segs.length - 1] === "~feedback") {
@@ -38773,7 +41158,10 @@ var DeviceHub = class {
    */
   async invoke(deviceId, req) {
     if (this.activeByDevice.has(deviceId)) return await this.invokeLocal(deviceId, req);
-    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    const offline = {
+      disposition: "not_dispatched",
+      result: { ok: false, error: TBError.deviceOffline().toJSON() }
+    };
     if (this.router === void 0) return offline;
     return await this.router.forward(deviceId, req) ?? offline;
   }
@@ -38784,7 +41172,10 @@ var DeviceHub = class {
    * 那会再次查路由并转发,在两个副本间弹来弹去。这里没有连接就直接 offline。
    */
   async invokeLocal(deviceId, req) {
-    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    const offline = {
+      disposition: "not_dispatched",
+      result: { ok: false, error: TBError.deviceOffline().toJSON() }
+    };
     const conn = this.activeByDevice.get(deviceId);
     if (conn === void 0) return offline;
     const authCtx = await identify(this.store, conn.authorization, (/* @__PURE__ */ new Date()).toISOString());
@@ -38803,7 +41194,10 @@ var DeviceHub = class {
       return offline;
     }
     if (this.activeByDevice.get(deviceId) !== conn) return offline;
-    return await new Promise((resolve3) => conn.session.call(req, resolve3));
+    return await new Promise((resolve3) => conn.session.call(
+      req,
+      (result, disposition) => resolve3({ disposition, result })
+    ));
   }
   /** DeviceChannel.ws:Node 宿主的升级在 http 层处理,永不应命中此路由。 */
   async ws() {
@@ -39080,7 +41474,13 @@ var DeviceRouter = class _DeviceRouter {
     return await new Promise((resolve3) => {
       const timer = setTimeout(() => {
         this.pending.delete(correlationId);
-        resolve3({ ok: false, error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u8D85\u65F6").toJSON() });
+        resolve3({
+          disposition: "unknown",
+          result: {
+            ok: false,
+            error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u8D85\u65F6").toJSON()
+          }
+        });
       }, this.opts.forwardTimeoutMs ?? DEVICE_FORWARD_TIMEOUT_MS);
       timer.unref?.();
       this.pending.set(correlationId, { resolve: resolve3, timer });
@@ -39090,8 +41490,11 @@ var DeviceRouter = class _DeviceRouter {
         this.pending.delete(correlationId);
         clearTimeout(waiter.timer);
         waiter.resolve({
-          ok: false,
-          error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+          disposition: "unknown",
+          result: {
+            ok: false,
+            error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+          }
         });
       });
     });
@@ -39101,7 +41504,13 @@ var DeviceRouter = class _DeviceRouter {
     this.renewTimer = void 0;
     for (const [, waiter] of this.pending) {
       clearTimeout(waiter.timer);
-      waiter.resolve({ ok: false, error: new TBError("unavailable", "\u7F51\u5173\u6B63\u5728\u5173\u95ED").toJSON() });
+      waiter.resolve({
+        disposition: "unknown",
+        result: {
+          ok: false,
+          error: new TBError("unavailable", "\u7F51\u5173\u6B63\u5728\u5173\u95ED").toJSON()
+        }
+      });
     }
     this.pending.clear();
     await Promise.all([...this.owned].map(async (id) => await this.release(id)));
@@ -39130,7 +41539,13 @@ var DeviceRouter = class _DeviceRouter {
     try {
       result = await this.opts.onLocalCall(call.deviceId, call.req);
     } catch {
-      result = { ok: false, error: new TBError("internal", "\u8BBE\u5907\u8C03\u7528\u6267\u884C\u5931\u8D25").toJSON() };
+      result = {
+        disposition: "unknown",
+        result: {
+          ok: false,
+          error: new TBError("internal", "\u8BBE\u5907\u8C03\u7528\u6267\u884C\u5931\u8D25").toJSON()
+        }
+      };
     }
     const reply = { correlationId: call.correlationId, result };
     await this.backend.publish(deviceReplyChannel(call.replyTo), JSON.stringify(reply)).catch(() => {
@@ -39414,6 +41829,41 @@ 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"]),
+  delivery: external_exports.enum(["realtime", "mailbox", "both"]).optional(),
+  confirm: external_exports.boolean().optional(),
+  timeoutMs: external_exports.number().int().positive().max(SHELL_EXEC_DEFAULT_TIMEOUT_MS).optional(),
+  maxOutputBytes: external_exports.number().int().positive().max(STRUCTURED_COMMAND_MAX_OUTPUT_BYTES).optional(),
+  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 +42147,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 +42337,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 +42481,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.17.0",
+  version: "0.20.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",
@@ -40370,26 +42820,27 @@ function createTbServer(config) {
   }
   const app = createTbApp(deps);
   let server;
-  let storeCleanupTimer;
-  let storeCleanupInFlight = false;
-  const runStoreCleanup = async () => {
-    if (storeCleanupInFlight) return;
-    storeCleanupInFlight = true;
+  let maintenanceTimer;
+  let maintenanceInFlight = false;
+  const runMaintenance = async () => {
+    if (maintenanceInFlight) return;
+    maintenanceInFlight = true;
     try {
       await cleanupDefaultStore(deps);
+      if (deps.encryptionKey !== void 0) await cleanupDeviceMailbox(deps);
     } finally {
-      storeCleanupInFlight = false;
+      maintenanceInFlight = false;
     }
   };
   const reportStoreCleanupFailure = () => {
     console.warn(JSON.stringify({ event: "tool_bridge_store_cleanup_failed" }));
   };
   const scheduleStoreCleanup = () => {
-    void runStoreCleanup().catch(reportStoreCleanupFailure);
-    storeCleanupTimer = setInterval(() => {
-      void runStoreCleanup().catch(reportStoreCleanupFailure);
+    void runMaintenance().catch(reportStoreCleanupFailure);
+    maintenanceTimer = setInterval(() => {
+      void runMaintenance().catch(reportStoreCleanupFailure);
     }, config.storeCleanupIntervalSec * 1e3);
-    storeCleanupTimer.unref?.();
+    maintenanceTimer.unref?.();
   };
   return {
     app,
@@ -40418,9 +42869,9 @@ function createTbServer(config) {
     },
     async close() {
       draining = true;
-      if (storeCleanupTimer !== void 0) {
-        clearInterval(storeCleanupTimer);
-        storeCleanupTimer = void 0;
+      if (maintenanceTimer !== void 0) {
+        clearInterval(maintenanceTimer);
+        maintenanceTimer = void 0;
       }
       let closed;
       if (server !== void 0) {