@tool-bridge/server 0.16.0 → 0.19.0

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

@@ -1,3 +1,6 @@
+import {
+  createGuardedFetch
+} from "./chunk-SWBNHIO4.js";
 import {
   AnnotationStore,
   CONTEXT_CAPABILITIES,
@@ -27,7 +30,6 @@ import {
   PG_SEARCH_TOOLS_TABLE,
   PG_SEARCH_WRITE_LOCK_KEY,
   PRESIGN_TTL_SEC_DEFAULT,
-  PRESIGN_TTL_SEC_MAX,
   RemoteAllowlistStore,
   SKILLHUB_CAPABILITIES,
   SKRegistryStore,
@@ -38,9 +40,11 @@ import {
   TB_ERROR_CODES,
   TOOL_SEARCH_AUDIT_NODE_LIMIT,
   TOOL_SEARCH_BATCH_LIMIT,
+  TOOL_SEARCH_DESCRIPTION_BYTES_MAX,
   TOOL_SEARCH_INSERT_SNAPSHOT_SQL,
   TOOL_SEARCH_INSERT_SQL,
   TOOL_SEARCH_PAGE_BYTES,
+  TOOL_SEARCH_RANKING_VERSION,
   TOOL_SEARCH_SCHEMA_STATEMENTS,
   TOOL_SEARCH_WORK_LIMIT,
   ZodIssueCode,
@@ -88,11 +92,24 @@ import {
   deviceFsHelpModel,
   deviceShellHelpModel,
   discriminatedUnion,
+  dispatchContextCmd,
+  dispatchContextUploadCmd,
+  dispatchSkillhubCmd,
   effectFor,
   email,
   encodeCallContext,
   encodeDeviceFrame,
   encodePluginCall,
+  external_exports,
+  feedbackDetailSchema,
+  feedbackListSchema,
+  feedbackRemoveResponseSchema,
+  feedbackSubmitRequestSchema,
+  feedbackSubmitResponseSchema,
+  feedbackViewSchema,
+  feedbackVoteRequestSchema,
+  healthResponseSchema,
+  helpJsonSchema,
   identify,
   intersection,
   isContextExpired,
@@ -101,31 +118,42 @@ import {
   iso_exports,
   lazy,
   literal,
+  livenessResponseSchema,
   looseObject,
   mintKey,
   negotiate,
-  normalizeCanonicalOrigin,
+  nodeInputSchema,
   normalizeEntryPath,
   normalizePath,
   normalizeToolSearchLimit,
+  normalizeToolSearchOptions,
   normalizeToolSearchPath,
   normalizeUpstreamError,
   number,
+  oauthAuthorizeRequestSchema,
+  oauthAuthorizeResponseSchema,
   object,
   objectBodyToBytes,
   optional,
   optionalMethodsForCapabilities,
+  parseContextCmdArgs,
   parseCredentialValues,
   parseFeedbackEntries,
   parseNodeInput,
+  parseNonNegativeIntEnv,
+  parsePortEnv,
+  parseRuntimeEnv,
   parseTokenResponse,
   parseVia,
   pgBulkInsertSql,
   pgSearchDialect,
   pluginTokenSecretName,
   prefixUpperBound,
+  prepareToolSearchQuery,
   preprocess,
+  readinessResponseSchema,
   record,
+  registryNodeSchema,
   renderHelpDsl,
   renderHelpJson,
   renderHelpMarkdown,
@@ -141,59 +169,42 @@ import {
   skillhubScopeForCmd,
   storeUri,
   string,
+  tbErrorBodySchema,
   toJSONSchema,
   toolHelpModel,
+  toolSearchPageSchema,
+  toolSearchRelevanceSchema,
+  toolSearchRequestSchema,
   toolSearchSnapshotDigest,
+  toolSearchSourceResultSchema,
+  toolSearchSourceSchema,
   toolsToHelpModel,
+  treeJsonSchema,
   union,
   unknown,
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-YB2FLNWI.js";
+} from "./chunk-OKRZPQ3R.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
-var DEFAULT_MAX_HOPS = 4;
 var DEFAULT_DEVICE_RECLAIM_SEC = 24 * 60 * 60;
 var DEFAULT_STORE_CLEANUP_INTERVAL_SEC = 15 * 60;
-function positiveIntEnv(value) {
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : void 0;
-}
-function presignTtlEnv(value) {
-  const ttl = positiveIntEnv(value);
-  return ttl === void 0 ? void 0 : Math.min(ttl, PRESIGN_TTL_SEC_MAX);
-}
-function portEnv(value) {
-  if (value === void 0 || value === "") return void 0;
-  const n = Number(value);
-  return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : void 0;
-}
 function configFromEnv(env = process.env) {
-  const allowInsecure = env.TB_ALLOW_INSECURE_HTTP === "true";
-  const allowlist = (env.TB_REMOTE_ALLOWLIST ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  const runtime = parseRuntimeEnv(env);
   const config = {
+    ...runtime,
     // TB_PORT 优先,PORT 兜底:Railway / Fly / Cloud Run / CF Container 等 PaaS 只注入
     // PORT,不认识 TB_PORT —— 不兜底的话容器会监听 8787 而平台探活另一个端口,部署直接失败。
-    port: portEnv(env.TB_PORT) ?? portEnv(env.PORT) ?? DEFAULT_PORT,
+    port: parsePortEnv(env.TB_PORT) ?? parsePortEnv(env.PORT) ?? DEFAULT_PORT,
     host: env.TB_HOST !== void 0 && env.TB_HOST.length > 0 ? env.TB_HOST : "0.0.0.0",
     dataDir: env.TB_DATA_DIR !== void 0 && env.TB_DATA_DIR.length > 0 ? env.TB_DATA_DIR : "./data",
-    allowInsecureHttp: allowInsecure,
     allowInsecureBootstrap: env.TB_ALLOW_INSECURE_BOOTSTRAP === "true",
-    remote: {
-      allowlist,
-      maxHops: positiveIntEnv(env.TB_MAX_HOPS) ?? DEFAULT_MAX_HOPS,
-      ...env.TB_INSTANCE_ID !== void 0 && env.TB_INSTANCE_ID.length > 0 ? { instanceId: env.TB_INSTANCE_ID } : {},
-      allowInsecure
-    },
-    deviceReclaimSec: positiveIntEnv(env.TB_DEVICE_RECLAIM_SEC) ?? DEFAULT_DEVICE_RECLAIM_SEC,
-    storeCleanupIntervalSec: positiveIntEnv(env.TB_STORE_CLEANUP_INTERVAL_SEC) ?? DEFAULT_STORE_CLEANUP_INTERVAL_SEC,
-    // 0 合法(立即关停,本地/单机默认);positiveIntEnv 拒 0,故单独解析。
-    shutdownDrainSec: (() => {
-      const n = Number(env.TB_SHUTDOWN_DRAIN_SEC);
-      return Number.isInteger(n) && n >= 0 ? n : 0;
-    })()
+    deviceReclaimSec: runtime.deviceReclaimSec ?? DEFAULT_DEVICE_RECLAIM_SEC,
+    storeCleanupIntervalSec: runtime.storeCleanupIntervalSec ?? DEFAULT_STORE_CLEANUP_INTERVAL_SEC,
+    // 0 合法(立即关停，本地/单机默认)。
+    shutdownDrainSec: parseNonNegativeIntEnv(env.TB_SHUTDOWN_DRAIN_SEC) ?? 0
   };
   if (env.TB_UI_DIR !== void 0 && env.TB_UI_DIR.length > 0) config.uiDir = env.TB_UI_DIR;
   if (env.TB_DATABASE_URL !== void 0 && env.TB_DATABASE_URL.length > 0) {
@@ -230,47 +241,9 @@ function configFromEnv(env = process.env) {
   if (env.TB_BOOTSTRAP_ADMIN_SK !== void 0 && env.TB_BOOTSTRAP_ADMIN_SK.length > 0) {
     config.adminSk = env.TB_BOOTSTRAP_ADMIN_SK;
   }
-  const canonicalOrigin = normalizeCanonicalOrigin(env.TB_CANONICAL_ORIGIN);
-  if (canonicalOrigin !== void 0) config.canonicalOrigin = canonicalOrigin;
   if (env.TB_SECRET_ENCRYPTION_KEY !== void 0 && env.TB_SECRET_ENCRYPTION_KEY.length > 0) {
     config.encryptionKey = env.TB_SECRET_ENCRYPTION_KEY;
   }
-  const ttl = positiveIntEnv(env.TB_TOOL_CACHE_TTL);
-  if (ttl !== void 0) config.toolCacheTtlSec = ttl;
-  const refThreshold = positiveIntEnv(env.TB_REF_THRESHOLD_BYTES);
-  if (refThreshold !== void 0) config.refThresholdBytes = refThreshold;
-  const refTtl = presignTtlEnv(env.TB_REF_TTL_SEC);
-  if (refTtl !== void 0) config.refTtlSec = refTtl;
-  const uploadGrantTtl = presignTtlEnv(env.TB_UPLOAD_GRANT_TTL_SEC);
-  if (uploadGrantTtl !== void 0) config.uploadGrantTtlSec = uploadGrantTtl;
-  const storeMaxObjectBytes = positiveIntEnv(env.TB_STORE_MAX_OBJECT_BYTES);
-  if (storeMaxObjectBytes !== void 0) config.storeMaxObjectBytes = storeMaxObjectBytes;
-  const storeRelayMaxBytes = positiveIntEnv(env.TB_STORE_RELAY_MAX_BYTES);
-  if (storeRelayMaxBytes !== void 0) config.storeRelayMaxBytes = storeRelayMaxBytes;
-  const storeUploadTtlSec = presignTtlEnv(env.TB_STORE_UPLOAD_TTL_SEC);
-  if (storeUploadTtlSec !== void 0) config.storeUploadTtlSec = storeUploadTtlSec;
-  const storeShareTtlSec = presignTtlEnv(env.TB_STORE_SHARE_TTL_SEC);
-  if (storeShareTtlSec !== void 0) config.storeShareTtlSec = storeShareTtlSec;
-  const storeReadTtlSec = presignTtlEnv(env.TB_STORE_READ_TTL_SEC);
-  if (storeReadTtlSec !== void 0) config.storeReadTtlSec = storeReadTtlSec;
-  const storeCallMaxBytes = positiveIntEnv(env.TB_STORE_CALL_MAX_BYTES);
-  if (storeCallMaxBytes !== void 0) config.storeCallMaxBytes = storeCallMaxBytes;
-  const storeCallMaxObjectBytes = positiveIntEnv(env.TB_STORE_CALL_MAX_OBJECT_BYTES);
-  if (storeCallMaxObjectBytes !== void 0) {
-    config.storeCallMaxObjectBytes = storeCallMaxObjectBytes;
-  }
-  const storeCallMaxObjects = positiveIntEnv(env.TB_STORE_CALL_MAX_OBJECTS);
-  if (storeCallMaxObjects !== void 0) config.storeCallMaxObjects = storeCallMaxObjects;
-  const storeCallAllowedContentTypes = (env.TB_STORE_CALL_ALLOWED_CONTENT_TYPES ?? "").split(",").map((value) => value.trim()).filter((value) => value.length > 0);
-  if (storeCallAllowedContentTypes.length > 0) {
-    config.storeCallAllowedContentTypes = storeCallAllowedContentTypes;
-  }
-  if (env.TB_STORE_TOKEN_SECRET !== void 0 && env.TB_STORE_TOKEN_SECRET.length > 0) {
-    if (env.TB_STORE_TOKEN_SECRET.length < 16) {
-      throw new Error("TB_STORE_TOKEN_SECRET \u81F3\u5C11\u9700\u8981 16 \u4E2A\u5B57\u7B26");
-    }
-    config.storeTokenSecret = env.TB_STORE_TOKEN_SECRET;
-  }
   return config;
 }
 
@@ -607,6 +580,48 @@ async function presignS3Put(client, url2, ttlSec, opts) {
   return { method: "PUT", url: signed.url, headers };
 }
 
+// ../app/src/objectBodyStream.ts
+function toWebObjectBodyStream(source, options = {}) {
+  const reader = source.getReader();
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    reader.releaseLock();
+  };
+  const strategy = options.highWaterMark === void 0 ? void 0 : { highWaterMark: options.highWaterMark };
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          release();
+          controller.close();
+        } else if (value !== void 0) {
+          controller.enqueue(value);
+        }
+      } catch (error) {
+        try {
+          release();
+        } catch {
+        }
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try {
+        if (reader.cancel !== void 0) await reader.cancel(reason);
+        else await source.cancel?.(reason);
+      } finally {
+        try {
+          release();
+        } catch {
+        }
+      }
+    }
+  }, strategy);
+}
+
 // ../app/src/providers/s3Object.ts
 var META_HEADER_PREFIX = "x-amz-meta-";
 function stripEtagQuotes(etag) {
@@ -637,16 +652,12 @@ function createS3ObjectStore(cfg, opts) {
   const secErr = assertSecureUrl(cfg.endpoint, opts.allowInsecure);
   if (secErr) throw secErr;
   const client = new AwsClient({
-    accessKeyId: cfg.accessKeyId,
-    secretAccessKey: cfg.secretAccessKey,
-    service: "s3",
-    region: cfg.region ?? "auto"
-  });
-  const putClient = new AwsClient({
     accessKeyId: cfg.accessKeyId,
     secretAccessKey: cfg.secretAccessKey,
     service: "s3",
     region: cfg.region ?? "auto",
+    // Store 的重试由上层按操作幂等性统一决定。传输层不得自动重放写入，
+    // 也不能让读/删路径悄悄继承 aws4fetch 的默认 10 次重试。
     retries: 0
   });
   const base = cfg.endpoint.replace(/\/+$/, "");
@@ -670,38 +681,7 @@ function createS3ObjectStore(cfg, opts) {
     if (body instanceof Uint8Array) {
       return body.buffer instanceof ArrayBuffer ? new Uint8Array(body.buffer, body.byteOffset, body.byteLength) : new Uint8Array(body);
     }
-    const source = body;
-    const reader = source.getReader();
-    return new ReadableStream({
-      async pull(controller) {
-        try {
-          const chunk = await reader.read();
-          if (chunk.done) {
-            reader.releaseLock();
-            controller.close();
-          } else if (chunk.value !== void 0) {
-            controller.enqueue(chunk.value);
-          }
-        } catch (error) {
-          try {
-            reader.releaseLock();
-          } catch {
-          }
-          controller.error(error);
-        }
-      },
-      async cancel(reason) {
-        try {
-          if (reader.cancel !== void 0) await reader.cancel(reason);
-          else await source.cancel?.(reason);
-        } finally {
-          try {
-            reader.releaseLock();
-          } catch {
-          }
-        }
-      }
-    }, { highWaterMark: 0 });
+    return toWebObjectBodyStream(body, { highWaterMark: 0 });
   };
   const metaFromHeaders = (key, headers) => {
     const metadata = {};
@@ -750,7 +730,7 @@ function createS3ObjectStore(cfg, opts) {
       }
       if (putOpts?.ifMatchEtag !== void 0) headers["if-match"] = `"${putOpts.ifMatchEtag}"`;
       if (putOpts?.ifNoneMatch !== void 0) headers["if-none-match"] = putOpts.ifNoneMatch;
-      const resp = await s3FetchWith(putClient, urlFor(key), {
+      const resp = await s3Fetch(urlFor(key), {
         method: "PUT",
         headers,
         body: fetchBody(body)
@@ -1256,8 +1236,8 @@ async function defaultStoreRuntime(deps) {
     service: new StoreService(deps.state, objects, serviceOptions(deps, tokenSecret))
   };
 }
-function requestOrigin(runtime, deps) {
-  const raw = deps.canonicalOrigin ?? runtime?.requestOrigin;
+function resolveStoreRequestOrigin(rawRequestOrigin, canonicalOrigin) {
+  const raw = rawRequestOrigin ?? canonicalOrigin;
   if (raw === void 0) {
     throw new TBError("unavailable", "request origin is unavailable", { retryable: false });
   }
@@ -1270,11 +1250,26 @@ function requestOrigin(runtime, deps) {
   if (url2.protocol !== "https:" && url2.protocol !== "http:" || url2.username !== "" || url2.password !== "") {
     throw new TBError("unavailable", "request origin is invalid", { retryable: false });
   }
+  if (rawRequestOrigin !== void 0 && canonicalOrigin !== void 0) {
+    let canonical;
+    try {
+      canonical = new URL(canonicalOrigin);
+    } catch {
+      throw new TBError("unavailable", "canonical origin is invalid", { retryable: false });
+    }
+    if (canonical.protocol !== "https:" && canonical.protocol !== "http:" || canonical.username !== "" || canonical.password !== "") {
+      throw new TBError("unavailable", "canonical origin is invalid", { retryable: false });
+    }
+    url2.protocol = canonical.protocol;
+  }
   return url2.origin;
 }
-function storeUploadGrant(start, origin2) {
+function requestOrigin(runtime, deps) {
+  return resolveStoreRequestOrigin(runtime?.requestOrigin, deps.canonicalOrigin);
+}
+function storeUploadGrant(start, origin) {
   const useRelay = start.alreadyCompleted || start.signedRequest === void 0;
-  const url2 = useRelay ? `${origin2}/~store/uploads/${encodeURIComponent(start.uploadId)}` : start.signedRequest.url;
+  const url2 = useRelay ? `${origin}/~store/uploads/${encodeURIComponent(start.uploadId)}` : start.signedRequest.url;
   const headers = useRelay ? { [STORE_UPLOAD_HEADER]: start.uploadToken } : start.signedRequest.headers;
   return {
     uploadId: start.uploadId,
@@ -1369,10 +1364,10 @@ function lazyDefaultStoreModule(deps) {
     }
   };
 }
-async function beginCapabilityUpload(deps, input, capabilityToken, origin2) {
+async function beginCapabilityUpload(deps, input, capabilityToken, origin) {
   const store = await defaultStoreRuntime(deps);
   const start = await store.service.beginCallUpload(input, capabilityToken);
-  return storeUploadGrant(start, origin2);
+  return storeUploadGrant(start, origin);
 }
 async function completeCapabilityUpload(deps, uploadId2, uploadToken) {
   return await (await defaultStoreRuntime(deps)).service.completeUploadWithToken(
@@ -1400,37 +1395,7 @@ async function relayStoreUpload(deps, uploadId2, uploadToken, body) {
 async function storeObjectResponse(objects, object2) {
   const got = await objects.get(object2.driverKey);
   if (got === null) throw TBError.notFound("not found");
-  const reader = got.body.getReader();
-  const body = new ReadableStream({
-    async pull(controller) {
-      try {
-        const chunk = await reader.read();
-        if (chunk.done) {
-          reader.releaseLock();
-          controller.close();
-        } else if (chunk.value !== void 0) {
-          controller.enqueue(chunk.value);
-        }
-      } catch (error) {
-        try {
-          reader.releaseLock();
-        } catch {
-        }
-        controller.error(error);
-      }
-    },
-    async cancel(reason) {
-      try {
-        if (reader.cancel !== void 0) await reader.cancel(reason);
-        else await got.body.cancel?.(reason);
-      } finally {
-        try {
-          reader.releaseLock();
-        } catch {
-        }
-      }
-    }
-  });
+  const body = toWebObjectBodyStream(got.body);
   return new Response(body, {
     headers: {
       "content-type": object2.contentType,
@@ -1502,7 +1467,6 @@ function cleanupProgress(value) {
     "objects",
     "shares",
     "callCapabilities",
-    "driverObjects",
     "idempotencyBindings"
   ]) {
     const cursor = cursors[field];
@@ -1516,7 +1480,6 @@ function emptyCleanupResult() {
   return {
     abandonedObjects: 0,
     deletedBytes: 0,
-    deletedOrphans: 0,
     deletedStaging: 0,
     expiredCallCapabilities: 0,
     expiredIdempotencyBindings: 0,
@@ -1527,7 +1490,6 @@ function emptyCleanupResult() {
 function addCleanupResult(target, page) {
   target.abandonedObjects += page.abandonedObjects;
   target.deletedBytes += page.deletedBytes;
-  target.deletedOrphans += page.deletedOrphans;
   target.deletedStaging += page.deletedStaging;
   target.expiredCallCapabilities += page.expiredCallCapabilities;
   target.expiredIdempotencyBindings += page.expiredIdempotencyBindings;
@@ -5804,8 +5766,8 @@ var LADDER_ERROR_HTTP_STATUS = {
 function parseSchema(schema, data) {
   return safeParse(schema, data);
 }
-function shapeKeys(schemas) {
-  return new Set(schemas.flatMap((schema) => Object.keys(schema.shape)));
+function shapeKeys(schemas2) {
+  return new Set(schemas2.flatMap((schema) => Object.keys(schema.shape)));
 }
 function isStandardSchema(schema) {
   if (schema == null) return false;
@@ -10068,13 +10030,13 @@ var require_utils = /* @__PURE__ */ __commonJSMin(((exports, module) => {
     const buffer = [];
     let endipv6Encountered = false;
     let endIpv6 = false;
-    let consume = consumeHextets;
+    let consume2 = consumeHextets;
     for (let i = 0; i < input.length; i++) {
       const cursor = input[i];
       if (cursor === "[" || cursor === "]") continue;
       if (cursor === ":") {
         if (endipv6Encountered === true) endIpv6 = true;
-        if (!consume(buffer, address, output)) break;
+        if (!consume2(buffer, address, output)) break;
         if (++tokenCount > 7) {
           output.error = true;
           break;
@@ -10083,14 +10045,14 @@ var require_utils = /* @__PURE__ */ __commonJSMin(((exports, module) => {
         address.push(":");
         continue;
       } else if (cursor === "%") {
-        if (!consume(buffer, address, output)) break;
-        consume = consumeIsZone;
+        if (!consume2(buffer, address, output)) break;
+        consume2 = consumeIsZone;
       } else {
         buffer.push(cursor);
         continue;
       }
     }
-    if (buffer.length) if (consume === consumeIsZone) output.zone = buffer.join("");
+    if (buffer.length) if (consume2 === consumeIsZone) output.zone = buffer.join("");
     else if (endIpv6) address.push(buffer.join(""));
     else address.push(stringArrayToHexStripped(buffer));
     output.address = address.join("");
@@ -10980,14 +10942,14 @@ var require_core$3 = /* @__PURE__ */ __commonJSMin(((exports) => {
       }
       return metaSchema;
     }
-    _removeAllSchemas(schemas, regex3) {
-      for (const keyRef in schemas) {
-        const sch = schemas[keyRef];
+    _removeAllSchemas(schemas2, regex3) {
+      for (const keyRef in schemas2) {
+        const sch = schemas2[keyRef];
         if (!regex3 || regex3.test(keyRef)) {
-          if (typeof sch == "string") delete schemas[keyRef];
+          if (typeof sch == "string") delete schemas2[keyRef];
           else if (sch && !sch.meta) {
             this._cache.delete(sch.schema);
-            delete schemas[keyRef];
+            delete schemas2[keyRef];
           }
         }
       }
@@ -19233,12 +19195,51 @@ async function invalidateMcpOAuth(store, nodePath) {
   await store.delete(KEY_OAUTH_TOKENS + nodePath);
   await store.delete(KEY_OAUTH_DISCOVERY + nodePath);
 }
+async function assertMcpOAuthConfig(config, secrets) {
+  if (config === null || typeof config !== "object") return;
+  const candidate = config;
+  if (candidate.kind !== "mcp" || candidate.oauthClient === void 0) return;
+  if (candidate.auth !== "oauth") {
+    throw new TBError("invalid_argument", "mcp oauthClient \u53EA\u80FD\u4E0E auth:'oauth' \u4E00\u8D77\u4F7F\u7528");
+  }
+  if (candidate.oauthClient === null || typeof candidate.oauthClient !== "object") {
+    throw new TBError("invalid_argument", "mcp oauthClient \u5FC5\u987B\u662F\u5BF9\u8C61");
+  }
+  const client = candidate.oauthClient;
+  const unknown2 = Object.keys(client).filter((key) => !["clientId", "clientSecretRef"].includes(key));
+  if (unknown2.length > 0) {
+    throw new TBError(
+      "invalid_argument",
+      `mcp oauthClient \u4E0D\u63A5\u53D7\u5B57\u6BB5:${unknown2.join(", ")};client secret \u5FC5\u987B\u8D70 clientSecretRef`
+    );
+  }
+  if (typeof client.clientId !== "string" || client.clientId.trim() === "") {
+    throw new TBError("invalid_argument", "mcp oauthClient.clientId \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (client.clientSecretRef === void 0) return;
+  if (typeof client.clientSecretRef !== "string" || client.clientSecretRef.trim() === "") {
+    throw new TBError("invalid_argument", "mcp oauthClient.clientSecretRef \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (await secrets.resolve(client.clientSecretRef) === void 0) {
+    throw new TBError(
+      "invalid_argument",
+      `OAuth client secret ref '${client.clientSecretRef}' \u4E0D\u5B58\u5728\u6216\u65E0\u6CD5\u89E3\u5BC6`
+    );
+  }
+}
 function reauthorizeRequired(nodePath) {
   return new TBError(
     "permission_denied",
     `mcp upstream '${nodePath}' requires (re)authorization: run \`tb tool auth ${nodePath}\``
   );
 }
+var mcpOAuthFetch = (input, init) => {
+  const headers = new Headers(
+    init?.headers ?? (input instanceof Request ? input.headers : void 0)
+  );
+  const tokenRequest = headers.get("content-type")?.toLowerCase().startsWith("application/x-www-form-urlencoded") === true;
+  return fetch(input, tokenRequest ? { ...init, redirect: "error" } : init);
+};
 async function stateCryptoKey(secret) {
   const digest = await crypto.subtle.digest(
     "SHA-256",
@@ -19270,7 +19271,7 @@ async function openOAuthState(state, secret) {
       ciphertext
     );
     const payload = JSON.parse(new TextDecoder().decode(plain));
-    if (typeof payload.p !== "string" || typeof payload.v !== "string" || typeof payload.exp !== "number" || payload.r !== void 0 && typeof payload.r !== "string") {
+    if (typeof payload.p !== "string" || typeof payload.v !== "string" || typeof payload.exp !== "number" || payload.r !== void 0 && typeof payload.r !== "string" || payload.o !== void 0 && (typeof payload.o !== "object" || payload.o === null || typeof payload.o.i !== "string" || payload.o.r !== void 0 && typeof payload.o.r !== "string")) {
       return null;
     }
     return payload;
@@ -19288,8 +19289,8 @@ var GatewayMcpOAuthProvider = class {
   }
   get redirectUrl() {
     if (this.opts.redirectUri !== void 0) return this.opts.redirectUri;
-    const origin2 = this.opts.origin ?? "https://tool-bridge.invalid";
-    return `${origin2}${OAUTH_CALLBACK_PATH}`;
+    const origin = this.opts.origin ?? "https://tool-bridge.invalid";
+    return `${origin}${OAUTH_CALLBACK_PATH}`;
   }
   get clientMetadata() {
     return {
@@ -19297,11 +19298,31 @@ var GatewayMcpOAuthProvider = class {
       redirect_uris: [this.redirectUrl],
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
-      token_endpoint_auth_method: "none"
-      // public client,PKCE 保护
+      // DCR 与 static public client 都是 PKCE public client；confidential client 由 AS
+      // metadata + client_secret 自动协商 basic/post，不在 metadata 里误声明 none。
+      ...this.opts.oauthClient?.clientSecretRef === void 0 ? { token_endpoint_auth_method: "none" } : {}
     };
   }
-  async clientInformation() {
+  async clientInformation(ctx) {
+    const configured = this.opts.oauthClient;
+    if (configured !== void 0) {
+      let clientSecret;
+      if (configured.clientSecretRef !== void 0) {
+        clientSecret = await this.opts.secrets.resolve(configured.clientSecretRef);
+        if (clientSecret === void 0) {
+          throw new TBError(
+            "unavailable",
+            `OAuth client secret ref '${configured.clientSecretRef}' \u4E0D\u5B58\u5728\u6216\u65E0\u6CD5\u89E3\u5BC6`,
+            { retryable: false }
+          );
+        }
+      }
+      return {
+        client_id: configured.clientId,
+        ...clientSecret !== void 0 ? { client_secret: clientSecret } : {},
+        ...ctx?.issuer !== void 0 ? { issuer: ctx.issuer } : {}
+      };
+    }
     const raw = await this.opts.store.get(KEY_OAUTH_CLIENT + this.opts.nodePath);
     if (raw === null) {
       if (this.opts.mode === "deny") throw reauthorizeRequired(this.opts.nodePath);
@@ -19310,14 +19331,47 @@ var GatewayMcpOAuthProvider = class {
     return raw;
   }
   async saveClientInformation(info) {
+    if (this.opts.oauthClient !== void 0) return;
     await this.opts.store.put(KEY_OAUTH_CLIENT + this.opts.nodePath, info);
   }
-  async tokens() {
+  async tokens(ctx) {
     const raw = await this.opts.store.get(KEY_OAUTH_TOKENS + this.opts.nodePath);
-    return raw === null ? void 0 : raw;
+    if (raw === null) return void 0;
+    const tokens = raw;
+    const discovery = await this.opts.store.get(KEY_OAUTH_DISCOVERY + this.opts.nodePath);
+    const discoveredIssuer = discovery?.authorizationServerMetadata?.issuer;
+    if (discoveredIssuer !== void 0 && tokens.issuer !== void 0 && tokens.issuer !== discoveredIssuer) {
+      await this.opts.store.delete(KEY_OAUTH_TOKENS + this.opts.nodePath);
+      return void 0;
+    }
+    let binding = tokens.toolBridgeBinding;
+    const client = await this.clientInformation(ctx);
+    if (binding === void 0 && this.opts.oauthClient === void 0 && client !== void 0 && "redirect_uris" in client && client.redirect_uris?.length === 1) {
+      binding = { clientId: client.client_id, redirectUri: client.redirect_uris[0] };
+      await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, {
+        ...tokens,
+        toolBridgeBinding: binding
+      });
+    }
+    const bindingMismatch = binding === void 0 || client === void 0 || binding.clientId !== client.client_id || this.opts.mode === "interactive" && binding.redirectUri !== this.redirectUrl;
+    if (bindingMismatch) {
+      await this.opts.store.delete(KEY_OAUTH_TOKENS + this.opts.nodePath);
+      return void 0;
+    }
+    return tokens;
   }
-  async saveTokens(tokens) {
-    await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, tokens);
+  async saveTokens(tokens, ctx) {
+    const client = await this.clientInformation(ctx);
+    if (client === void 0) throw new TBError("internal", "OAuth client information missing");
+    const previous = await this.opts.store.get(KEY_OAUTH_TOKENS + this.opts.nodePath);
+    const redirectUri = this.opts.mode === "interactive" ? this.redirectUrl : previous?.toolBridgeBinding?.redirectUri ?? ("redirect_uris" in client && client.redirect_uris?.length === 1 ? client.redirect_uris[0] : void 0);
+    if (redirectUri === void 0) {
+      throw new TBError("permission_denied", "OAuth grant redirect binding missing; reauthorize");
+    }
+    await this.opts.store.put(KEY_OAUTH_TOKENS + this.opts.nodePath, {
+      ...tokens,
+      toolBridgeBinding: { clientId: client.client_id, redirectUri }
+    });
   }
   async saveCodeVerifier(codeVerifier) {
     this.verifier = codeVerifier;
@@ -19339,7 +19393,13 @@ var GatewayMcpOAuthProvider = class {
         p: this.opts.nodePath,
         v: this.codeVerifier(),
         exp: Math.floor(Date.now() / 1e3) + STATE_TTL_SEC,
-        ...this.opts.redirectUri !== void 0 ? { r: this.opts.redirectUri } : {}
+        r: this.redirectUrl,
+        ...this.opts.oauthClient !== void 0 ? {
+          o: {
+            i: this.opts.oauthClient.clientId,
+            ...this.opts.oauthClient.clientSecretRef !== void 0 ? { r: this.opts.oauthClient.clientSecretRef } : {}
+          }
+        } : {}
       },
       this.opts.encryptionKey
     );
@@ -19356,7 +19416,9 @@ var GatewayMcpOAuthProvider = class {
   /** SDK 对 InvalidClient/InvalidGrant 等可恢复错误的重试钩子:清对应缓存后重走。 */
   async invalidateCredentials(scope) {
     const { store, nodePath } = this.opts;
-    if (scope === "all" || scope === "client") await store.delete(KEY_OAUTH_CLIENT + nodePath);
+    if ((scope === "all" || scope === "client") && this.opts.oauthClient === void 0) {
+      await store.delete(KEY_OAUTH_CLIENT + nodePath);
+    }
     if (scope === "all" || scope === "tokens") await store.delete(KEY_OAUTH_TOKENS + nodePath);
     if (scope === "all" || scope === "discovery") await store.delete(KEY_OAUTH_DISCOVERY + nodePath);
     if (scope === "all" || scope === "verifier") this.verifier = void 0;
@@ -19383,6 +19445,13 @@ async function guardOAuth(fn) {
     return await fn();
   } catch (err) {
     if (err instanceof TBError) throw err;
+    if (err instanceof Error && /does not support dynamic client registration/i.test(err.message)) {
+      throw new TBError(
+        "invalid_argument",
+        "authorization server \u672A\u63D0\u4F9B\u52A8\u6001\u5BA2\u6237\u7AEF\u6CE8\u518C\uFF1B\u8BF7\u914D\u7F6E\u9884\u6CE8\u518C OAuth client(CLI: --oauth-client-id\uFF0C\u53EF\u9009 --oauth-client-secret-ref)",
+        { retryable: false }
+      );
+    }
     throw new TBError(
       "unavailable",
       `OAuth flow failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -19391,11 +19460,13 @@ async function guardOAuth(fn) {
   }
 }
 async function startMcpAuthorization(opts) {
-  if (opts.redirectUri !== void 0) {
-    assertLocalRedirectUri(opts.redirectUri);
+  if (opts.redirectUri !== void 0) assertLocalRedirectUri(opts.redirectUri);
+  const redirectUri = opts.redirectUri ?? `${opts.origin}${OAUTH_CALLBACK_PATH}`;
+  if (opts.oauthClient === void 0) {
     const cached = await opts.store.get(KEY_OAUTH_CLIENT + opts.nodePath);
-    if (cached !== null && !(cached.redirect_uris ?? []).includes(opts.redirectUri)) {
+    if (cached !== null && !(cached.redirect_uris ?? []).includes(redirectUri)) {
       await opts.store.delete(KEY_OAUTH_CLIENT + opts.nodePath);
+      await opts.store.delete(KEY_OAUTH_TOKENS + opts.nodePath);
     }
   }
   const provider = new GatewayMcpOAuthProvider({
@@ -19404,10 +19475,12 @@ async function startMcpAuthorization(opts) {
     encryptionKey: opts.encryptionKey,
     mode: "interactive",
     origin: opts.origin,
+    secrets: opts.secrets,
+    ...opts.oauthClient !== void 0 ? { oauthClient: opts.oauthClient } : {},
     ...opts.redirectUri !== void 0 ? { redirectUri: opts.redirectUri } : {}
   });
   return await guardOAuth(async () => {
-    const result = await auth(provider, { serverUrl: opts.serverUrl });
+    const result = await auth(provider, { serverUrl: opts.serverUrl, fetchFn: mcpOAuthFetch });
     if (result === "AUTHORIZED") return { status: "authorized" };
     const url2 = provider.capturedAuthorizationUrl;
     if (url2 === void 0) {
@@ -19423,13 +19496,17 @@ async function finishMcpAuthorization(opts) {
     encryptionKey: opts.encryptionKey,
     mode: "interactive",
     origin: opts.origin,
+    secrets: opts.secrets,
+    ...opts.oauthClient !== void 0 ? { oauthClient: opts.oauthClient } : {},
     ...opts.redirectUri !== void 0 ? { redirectUri: opts.redirectUri } : {}
   });
   provider.setCodeVerifier(opts.codeVerifier);
   await guardOAuth(async () => {
     const result = await auth(provider, {
       serverUrl: opts.serverUrl,
-      authorizationCode: opts.code
+      authorizationCode: opts.code,
+      fetchFn: mcpOAuthFetch,
+      ...opts.authorizationResponseIssuer !== void 0 ? { iss: opts.authorizationResponseIssuer } : {}
     });
     if (result !== "AUTHORIZED") {
       throw new TBError("internal", "authorization did not complete");
@@ -19496,7 +19573,7 @@ var noStandaloneSseFetch = (input, init) => {
   if (String(method).toUpperCase() === "GET" && accept.includes("text/event-stream")) {
     return Promise.resolve(new Response(null, { status: 405, statusText: "Method Not Allowed" }));
   }
-  return fetch(input, init);
+  return mcpOAuthFetch(input, init);
 };
 var ERA_KEY_PREFIX = "mcpera:";
 var LEGACY_ERA_HORIZON_SEC = 300;
@@ -19636,7 +19713,9 @@ function createMcpProvider(config, secrets, opts) {
           store: opts.oauth.store,
           nodePath,
           encryptionKey: opts.oauth.encryptionKey,
-          mode: "deny"
+          mode: "deny",
+          secrets,
+          ...config.oauthClient !== void 0 ? { oauthClient: config.oauthClient } : {}
         })
       };
     }
@@ -19738,15 +19817,6 @@ async function clientCredential(secrets, authRef) {
     ...values.clientSecret === void 0 ? {} : { clientSecret: values.clientSecret }
   };
 }
-function parseTokenErrorMessage(payload) {
-  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
-  const record2 = payload;
-  for (const key of ["error_description", "error", "msg", "message"]) {
-    const value = record2[key];
-    if (typeof value === "string" && value !== "") return value;
-  }
-  return void 0;
-}
 async function writeTokens(store, nodePath, next, previous) {
   const merged = {
     ...next,
@@ -19770,10 +19840,10 @@ async function requestTokens(opts) {
   let response;
   try {
     response = await opts.fetcher(endpoint, { method: "POST", headers, body });
-  } catch (err) {
+  } catch {
     throw new TBError(
       "unavailable",
-      `\u4EE4\u724C\u7AEF\u70B9\u4E0D\u53EF\u8FBE:${err instanceof Error ? err.message : String(err)}`,
+      "\u4EE4\u724C\u7AEF\u70B9\u4E0D\u53EF\u8FBE",
       { retryable: true }
     );
   }
@@ -19785,14 +19855,20 @@ async function requestTokens(opts) {
     payload = null;
   }
   if (!response.ok) {
-    const parsed = payload === null ? void 0 : parseTokenErrorMessage(payload);
-    const detail = parsed ?? `HTTP ${response.status}`;
+    const detail = `HTTP ${response.status}`;
     if (response.status >= 500) {
       throw new TBError("unavailable", `\u4EE4\u724C\u7AEF\u70B9\u8FD4\u56DE ${detail}`, { retryable: true });
     }
     throw new TBError("invalid_argument", `\u4EE4\u724C\u7AEF\u70B9\u62D2\u7EDD\u4E86\u8BF7\u6C42:${detail}`);
   }
-  return parseTokenResponse(payload, opts.config, opts.now);
+  try {
+    return parseTokenResponse(payload, opts.config, opts.now);
+  } catch (err) {
+    if (isTBError(err) && err.code === "invalid_argument") {
+      throw new TBError("invalid_argument", "\u4EE4\u724C\u7AEF\u70B9\u8FD4\u56DE\u4E86\u65E0\u6548\u54CD\u5E94");
+    }
+    throw err;
+  }
 }
 function base64url(bytes) {
   let binary = "";
@@ -19804,7 +19880,14 @@ async function createPkce() {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
   return { verifier, challenge: base64url(new Uint8Array(digest)) };
 }
+function requireProviderOAuthFetch(fetcher) {
+  if (fetcher === void 0) {
+    throw new TBError("unavailable", "Provider OAuth \u51FA\u7AD9\u901A\u9053\u672A\u914D\u7F6E", { retryable: false });
+  }
+  return fetcher;
+}
 async function startProviderAuthorization(opts) {
+  const fetcher = requireProviderOAuthFetch(opts.fetcher);
   const existing = await readTokens(opts.store, opts.nodePath);
   if (existing !== void 0 && !shouldRefresh(existing, opts.now)) {
     return { status: "authorized" };
@@ -19814,7 +19897,7 @@ async function startProviderAuthorization(opts) {
       const client2 = await clientCredential(opts.secrets, opts.authRef);
       const refreshed = await requestTokens({
         config: opts.config,
-        fetcher: opts.fetcher,
+        fetcher,
         now: opts.now,
         grant: { refreshToken: existing.refreshToken },
         ...client2
@@ -19847,10 +19930,11 @@ async function startProviderAuthorization(opts) {
   };
 }
 async function finishProviderAuthorization(opts) {
+  const fetcher = requireProviderOAuthFetch(opts.fetcher);
   const client = await clientCredential(opts.secrets, opts.authRef);
   const tokens = await requestTokens({
     config: opts.config,
-    fetcher: opts.fetcher,
+    fetcher,
     now: opts.now,
     grant: { code: opts.code, redirectUri: opts.origin + PROVIDER_OAUTH_CALLBACK_PATH },
     ...opts.codeVerifier === "" ? {} : { codeVerifier: opts.codeVerifier },
@@ -19859,6 +19943,7 @@ async function finishProviderAuthorization(opts) {
   await writeTokens(opts.store, opts.nodePath, tokens);
 }
 async function resolveProviderAccessToken(opts) {
+  const fetcher = requireProviderOAuthFetch(opts.fetcher);
   const tokens = await readTokens(opts.store, opts.nodePath);
   if (tokens === void 0) throw providerReauthorizeRequired(opts.nodePath);
   if (opts.force !== true && !shouldRefresh(tokens, opts.now)) return tokens.accessToken;
@@ -19868,7 +19953,7 @@ async function resolveProviderAccessToken(opts) {
   try {
     refreshed = await requestTokens({
       config: opts.config,
-      fetcher: opts.fetcher,
+      fetcher,
       now: opts.now,
       grant: { refreshToken: tokens.refreshToken },
       ...client
@@ -19972,7 +20057,7 @@ async function providerAccessTokenFor(opts) {
     config: opts.config,
     encryptionKey,
     ...opts.force === true ? { force: true } : {},
-    fetcher: fetch,
+    fetcher: opts.deps.providerOAuthFetch,
     nodePath: opts.nodePath,
     now: /* @__PURE__ */ new Date(),
     // 调用期不需要 origin(只在构造授权 URL 时用);传空串会被 buildAuthorizationUrl 用到,
@@ -20313,11 +20398,11 @@ async function contextProviderFor(node, cfg, deps, requestUrl) {
   if (deps.refTtlSec !== void 0) opts.presignTtlSec = deps.refTtlSec;
   const encKey = deps.encryptionKey;
   if (encKey !== void 0) {
-    const origin2 = new URL(requestUrl).origin;
+    const origin = new URL(requestUrl).origin;
     const relayTtlSec = deps.refTtlSec ?? PRESIGN_TTL_SEC_DEFAULT;
     opts.relayRefUrl = async (key) => {
       const exp = Math.floor(Date.now() / 1e3) + relayTtlSec;
-      return `${origin2}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
+      return `${origin}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
     };
   }
   return createObjectContextProvider(objects, opts);
@@ -20338,69 +20423,20 @@ async function skillhubProviderFor(node, cfg, deps, requestUrl) {
   if (deps.refTtlSec !== void 0) opts.presignTtlSec = deps.refTtlSec;
   const encKey = deps.encryptionKey;
   if (encKey !== void 0) {
-    const origin2 = new URL(requestUrl).origin;
+    const origin = new URL(requestUrl).origin;
     const relayTtlSec = deps.refTtlSec ?? PRESIGN_TTL_SEC_DEFAULT;
     opts.relayRefUrl = async (key) => {
       const exp = Math.floor(Date.now() / 1e3) + relayTtlSec;
-      return `${origin2}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
+      return `${origin}/~ref/${await signRefToken({ p: node.path, k: key, exp }, encKey)}`;
     };
   }
   return createSkillhubProvider(objects, opts);
 }
-async function dispatchSkillhubCmd(provider, command, args) {
-  switch (command.toLowerCase()) {
-    case "list":
-      return await provider.list(args.opts);
-    case "get":
-      return typeof args.file === "string" ? await provider.get_file(args.id, args.file) : await provider.get(args.id);
-    case "search":
-      return await provider.search(args.query, args.opts);
-    case "publish":
-      if (!Array.isArray(args.files)) {
-        throw new TBError("invalid_argument", "publish \u9700\u8981\u6570\u7EC4 'files'");
-      }
-      return await provider.publish({
-        ...typeof args.id === "string" ? { id: args.id } : {},
-        files: args.files
-      });
-    case "remove":
-      return await provider.remove(args.id);
-    default:
-      throw new TBError("invalid_argument", `unknown cmd '${command}'`);
-  }
-}
-async function dispatchContextCmd(provider, command, args) {
-  const unimplemented = () => {
-    throw new TBError("invalid_argument", `unknown cmd '${command}'(provider \u672A\u5B9E\u73B0)`);
-  };
-  switch (command.toLowerCase()) {
-    case "list":
-      if (provider.list === void 0) return unimplemented();
-      return await provider.list(args.path ?? "", args.opts);
-    case "get":
-      if (provider.get === void 0) return unimplemented();
-      return await provider.get(args.path);
-    case "write":
-      if (provider.write === void 0) return unimplemented();
-      if (typeof args.entry !== "object" || args.entry === null) {
-        throw new TBError("invalid_argument", "write \u9700\u8981\u5BF9\u8C61 'entry'");
-      }
-      return await provider.write(args.path, args.entry);
-    case "update":
-      if (provider.update === void 0) return unimplemented();
-      if (typeof args.patch !== "object" || args.patch === null) {
-        throw new TBError("invalid_argument", "update \u9700\u8981\u5BF9\u8C61 'patch'");
-      }
-      return await provider.update(args.path, args.patch);
-    case "delete":
-      if (provider.delete === void 0) return unimplemented();
-      return await provider.delete(args.path);
-    case "search":
-      if (provider.search === void 0) return unimplemented();
-      return await provider.search(args.query, args.opts);
-    default:
-      throw new TBError("invalid_argument", `unknown cmd '${command}'`);
-  }
+async function dispatchSkillhubCmd2(provider, command, args) {
+  return await dispatchSkillhubCmd(provider, command, args);
+}
+async function dispatchContextCmd2(provider, command, args) {
+  return await dispatchContextCmd(provider, command, args);
 }
 async function assertContextAlive(node, cfg, registry) {
   if (!isContextExpired(node.createdAt, cfg.ttl, Date.now())) return;
@@ -23845,8 +23881,8 @@ var LADDER_ERROR_HTTP_STATUS2 = {
   [ProtocolErrorCode2.MissingRequiredClientCapability]: 400,
   [HEADER_MISMATCH_ERROR_CODE2]: 400
 };
-function httpStatusForErrorCode(code, origin2) {
-  if (origin2 === "in-band") return code === ProtocolErrorCode2.MissingRequiredClientCapability ? 400 : 200;
+function httpStatusForErrorCode(code, origin) {
+  if (origin === "in-band") return code === ProtocolErrorCode2.MissingRequiredClientCapability ? 400 : 200;
   return LADDER_ERROR_HTTP_STATUS2[code] ?? 400;
 }
 function rejection(rung, cell, httpStatus, error, settled) {
@@ -24059,8 +24095,8 @@ function modernOnlyStrictRejection(route, supportedVersions) {
 function parseSchema2(schema, data) {
   return safeParse(schema, data);
 }
-function shapeKeys2(schemas) {
-  return new Set(schemas.flatMap((schema) => Object.keys(schema.shape)));
+function shapeKeys2(schemas2) {
+  return new Set(schemas2.flatMap((schema) => Object.keys(schema.shape)));
 }
 function isStandardSchema2(schema) {
   if (schema == null) return false;
@@ -28245,13 +28281,13 @@ var require_utils2 = /* @__PURE__ */ __commonJSMin2(((exports, module) => {
     const buffer = [];
     let endipv6Encountered = false;
     let endIpv6 = false;
-    let consume = consumeHextets;
+    let consume2 = consumeHextets;
     for (let i = 0; i < input.length; i++) {
       const cursor = input[i];
       if (cursor === "[" || cursor === "]") continue;
       if (cursor === ":") {
         if (endipv6Encountered === true) endIpv6 = true;
-        if (!consume(buffer, address, output)) break;
+        if (!consume2(buffer, address, output)) break;
         if (++tokenCount > 7) {
           output.error = true;
           break;
@@ -28260,14 +28296,14 @@ var require_utils2 = /* @__PURE__ */ __commonJSMin2(((exports, module) => {
         address.push(":");
         continue;
       } else if (cursor === "%") {
-        if (!consume(buffer, address, output)) break;
-        consume = consumeIsZone;
+        if (!consume2(buffer, address, output)) break;
+        consume2 = consumeIsZone;
       } else {
         buffer.push(cursor);
         continue;
       }
     }
-    if (buffer.length) if (consume === consumeIsZone) output.zone = buffer.join("");
+    if (buffer.length) if (consume2 === consumeIsZone) output.zone = buffer.join("");
     else if (endIpv6) address.push(buffer.join(""));
     else address.push(stringArrayToHexStripped(buffer));
     output.address = address.join("");
@@ -29157,14 +29193,14 @@ var require_core$32 = /* @__PURE__ */ __commonJSMin2(((exports) => {
       }
       return metaSchema;
     }
-    _removeAllSchemas(schemas, regex3) {
-      for (const keyRef in schemas) {
-        const sch = schemas[keyRef];
+    _removeAllSchemas(schemas2, regex3) {
+      for (const keyRef in schemas2) {
+        const sch = schemas2[keyRef];
         if (!regex3 || regex3.test(keyRef)) {
-          if (typeof sch == "string") delete schemas[keyRef];
+          if (typeof sch == "string") delete schemas2[keyRef];
           else if (sch && !sch.meta) {
             this._cache.delete(sch.schema);
-            delete schemas[keyRef];
+            delete schemas2[keyRef];
           }
         }
       }
@@ -36438,6 +36474,121 @@ function createPluginContextProvider(opts) {
 
 // ../app/src/providers/remote.ts
 var VIA_HEADER = "x-tb-via";
+function remoteAbortError() {
+  return new TBError("unavailable", "remote request aborted", { retryable: true });
+}
+function remoteResponseTooLarge(maxBytes) {
+  return new TBError(
+    "unavailable",
+    `remote response body exceeds ${maxBytes} bytes`,
+    { retryable: false }
+  );
+}
+function isAbortError(error, signal) {
+  return signal?.aborted === true || error instanceof Error && error.name === "AbortError";
+}
+function signalAborted(signal) {
+  return signal?.aborted === true;
+}
+function declaredContentLength(response) {
+  const value = response.headers.get("content-length");
+  if (value === null || !/^\d+$/.test(value)) return void 0;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+async function readRemoteResponseBody(response, maxBytes, signal) {
+  if (signal?.aborted === true) throw remoteAbortError();
+  const declared = declaredContentLength(response);
+  if (maxBytes !== void 0 && declared !== void 0 && declared > maxBytes) {
+    void response.body?.cancel().catch(() => {
+    });
+    throw remoteResponseTooLarge(maxBytes);
+  }
+  if (response.body === null) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  let abortListener;
+  const abortPromise = signal === void 0 ? void 0 : new Promise((_resolve, reject) => {
+    abortListener = () => {
+      reject(remoteAbortError());
+      void reader.cancel().catch(() => {
+      });
+    };
+    signal.addEventListener("abort", abortListener, { once: true });
+    if (signal.aborted) abortListener();
+  });
+  try {
+    while (true) {
+      const result = await (abortPromise === void 0 ? reader.read() : Promise.race([reader.read(), abortPromise]));
+      if (signalAborted(signal)) throw remoteAbortError();
+      if (result.done) break;
+      total += result.value.byteLength;
+      if (maxBytes !== void 0 && total > maxBytes) {
+        void reader.cancel().catch(() => {
+        });
+        throw remoteResponseTooLarge(maxBytes);
+      }
+      chunks.push(result.value);
+    }
+  } catch (error) {
+    if (error instanceof TBError) throw error;
+    if (isAbortError(error, signal)) throw remoteAbortError();
+    throw normalizeUpstreamError({
+      kind: "network",
+      message: "failed to read remote response body"
+    });
+  } finally {
+    if (abortListener !== void 0) signal?.removeEventListener("abort", abortListener);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+var DEFAULT_FEDERATED_SEARCH_SETTINGS = {
+  maxConcurrency: 4,
+  maxResponseBodyBytes: 512 * 1024,
+  maxSources: 16,
+  minChildWorkMs: 200,
+  perHopReturnReserveMs: 100,
+  sessionTtlMs: 5 * 60 * 1e3,
+  totalDeadlineMs: 2500
+};
+function federatedSearchSettings(settings) {
+  const configured = settings.federatedSearch ?? {};
+  const positive = (value, fallback) => value !== void 0 && Number.isFinite(value) && Number.isInteger(value) && value > 0 ? value : fallback;
+  return {
+    maxConcurrency: positive(
+      configured.maxConcurrency,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.maxConcurrency
+    ),
+    maxResponseBodyBytes: positive(
+      configured.maxResponseBodyBytes,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.maxResponseBodyBytes
+    ),
+    maxSources: positive(configured.maxSources, DEFAULT_FEDERATED_SEARCH_SETTINGS.maxSources),
+    minChildWorkMs: positive(
+      configured.minChildWorkMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.minChildWorkMs
+    ),
+    perHopReturnReserveMs: positive(
+      configured.perHopReturnReserveMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.perHopReturnReserveMs
+    ),
+    sessionTtlMs: positive(
+      configured.sessionTtlMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.sessionTtlMs
+    ),
+    totalDeadlineMs: positive(
+      configured.totalDeadlineMs,
+      DEFAULT_FEDERATED_SEARCH_SETTINGS.totalDeadlineMs
+    )
+  };
+}
 function selfInstanceId(settings, requestUrl) {
   if (settings.instanceId !== void 0 && settings.instanceId.length > 0) {
     return settings.instanceId;
@@ -36456,6 +36607,13 @@ function assertRemoteAllowed(baseUrl, settings) {
   }
 }
 async function passthroughRemote(opts) {
+  if (opts.maxResponseBodyBytes !== void 0 && (!Number.isSafeInteger(opts.maxResponseBodyBytes) || opts.maxResponseBodyBytes < 0)) {
+    throw new TBError(
+      "invalid_argument",
+      "maxResponseBodyBytes must be a non-negative safe integer"
+    );
+  }
+  if (opts.signal?.aborted === true) throw remoteAbortError();
   const secErr = assertSecureUrl(opts.config.baseUrl, opts.settings.allowInsecure);
   if (secErr) throw secErr;
   if (!checkAllowlist(opts.config.baseUrl, opts.settings.allowlist)) {
@@ -36480,6 +36638,16 @@ async function passthroughRemote(opts) {
   if (accept !== null) outHeaders.accept = accept;
   const contentType = opts.headers.get("content-type");
   if (contentType !== null) outHeaders["content-type"] = contentType;
+  for (const name of [
+    "x-tb-search-remaining-ms",
+    "x-tb-search-session-ttl-ms",
+    "x-tb-search-source-budget",
+    "x-tb-search-validate-snapshot",
+    "x-tb-search-want-snapshot"
+  ]) {
+    const value = opts.headers.get(name);
+    if (value !== null) outHeaders[name] = value;
+  }
   if (opts.config.skRef !== void 0) {
     const cred = await opts.secrets.resolve(opts.config.skRef);
     if (cred === void 0) {
@@ -36507,22 +36675,304 @@ 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
 import { Hono } from "hono";
 
+// ../core/src/protocol/openapi.ts
+var schemaRegistry = external_exports.registry();
+var schemas = {
+  Error: tbErrorBodySchema,
+  FeedbackDetail: feedbackDetailSchema,
+  FeedbackList: feedbackListSchema,
+  FeedbackRemoveResponse: feedbackRemoveResponseSchema,
+  FeedbackSubmitRequest: feedbackSubmitRequestSchema,
+  FeedbackSubmitResponse: feedbackSubmitResponseSchema,
+  FeedbackView: feedbackViewSchema,
+  FeedbackVoteRequest: feedbackVoteRequestSchema,
+  Health: healthResponseSchema,
+  Help: helpJsonSchema,
+  Liveness: livenessResponseSchema,
+  NodeInput: nodeInputSchema,
+  OAuthAuthorizeRequest: oauthAuthorizeRequestSchema,
+  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 });
+function asOpenApiSchema(value) {
+  if (Array.isArray(value)) return value.map(asOpenApiSchema);
+  if (value === null || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "$schema") continue;
+    if (key === "$ref" && typeof entry === "string" && !entry.startsWith("#/")) {
+      out[key] = `#/components/schemas/${entry}`;
+    } else {
+      out[key] = asOpenApiSchema(entry);
+    }
+  }
+  return out;
+}
+var generated = external_exports.toJSONSchema(schemaRegistry);
+var componentSchemas = Object.fromEntries(
+  Object.entries(generated.schemas).map(([name, schema]) => [name, asOpenApiSchema(schema)])
+);
+var jsonContent = (schema) => ({
+  "application/json": { schema: { $ref: `#/components/schemas/${schema}` } }
+});
+var jsonResponse = (description, schema) => ({
+  description,
+  content: jsonContent(schema)
+});
+var errorResponses = {
+  400: jsonResponse("Invalid request", "Error"),
+  401: jsonResponse("Unauthenticated", "Error"),
+  403: jsonResponse("Permission denied", "Error"),
+  404: jsonResponse("Not found or not visible", "Error"),
+  409: jsonResponse("Conflict", "Error"),
+  429: jsonResponse("Rate limited", "Error"),
+  500: jsonResponse("Internal error", "Error"),
+  503: jsonResponse("Unavailable", "Error")
+};
+var bearerSecurity = [{ bearerAuth: [] }];
+var pathParameter = {
+  in: "path",
+  name: "path",
+  required: true,
+  description: "Slash-delimited Tool Bridge tree path; each segment is URL encoded.",
+  schema: { type: "string" }
+};
+var fixedControlPlaneOpenApi = {
+  openapi: "3.1.0",
+  info: {
+    title: "Tool Bridge fixed control plane",
+    version: "1.0.0"
+  },
+  components: {
+    securitySchemes: {
+      bearerAuth: { type: "http", scheme: "bearer" }
+    },
+    schemas: componentSchemas
+  },
+  paths: {
+    "/healthz": {
+      get: {
+        operationId: "getHealth",
+        security: [],
+        responses: { 200: jsonResponse("Deployment health", "Health") }
+      }
+    },
+    "/livez": {
+      get: {
+        operationId: "getLiveness",
+        security: [],
+        responses: { 200: jsonResponse("Process liveness", "Liveness") }
+      }
+    },
+    "/readyz": {
+      get: {
+        operationId: "getReadiness",
+        security: [],
+        responses: {
+          200: jsonResponse("Ready", "Readiness"),
+          503: jsonResponse("Not ready", "Readiness")
+        }
+      }
+    },
+    "/~help": {
+      get: {
+        operationId: "getRootHelp",
+        security: bearerSecurity,
+        parameters: [{
+          in: "query",
+          name: "schemas",
+          schema: { type: "string", enum: ["1"] }
+        }],
+        responses: { 200: jsonResponse("Root HTBP help", "Help"), ...errorResponses }
+      }
+    },
+    "/{path}/~help": {
+      get: {
+        "operationId": "getHelp",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, {
+          in: "query",
+          name: "schemas",
+          schema: { type: "string", enum: ["1"] }
+        }],
+        "responses": { 200: jsonResponse("HTBP help", "Help"), ...errorResponses },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/~tree": {
+      get: {
+        operationId: "getRootTree",
+        security: bearerSecurity,
+        parameters: [{ in: "query", name: "depth", schema: { type: "integer", minimum: 1, maximum: 8 } }],
+        responses: { 200: jsonResponse("Root tree", "Tree"), ...errorResponses }
+      }
+    },
+    "/{path}/~tree": {
+      get: {
+        "operationId": "getTree",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, {
+          in: "query",
+          name: "depth",
+          schema: { type: "integer", minimum: 1, maximum: 8 }
+        }],
+        "responses": { 200: jsonResponse("Subtree", "Tree"), ...errorResponses },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/~search": {
+      post: {
+        operationId: "searchTools",
+        security: bearerSecurity,
+        requestBody: { required: true, content: jsonContent("SearchRequest") },
+        responses: { 200: jsonResponse("Visible tool page", "SearchResponse"), ...errorResponses }
+      }
+    },
+    "/{path}/~authorize": {
+      post: {
+        "operationId": "startOAuthAuthorization",
+        "security": bearerSecurity,
+        "parameters": [pathParameter],
+        "requestBody": { required: false, content: jsonContent("OAuthAuthorizeRequest") },
+        "responses": {
+          200: jsonResponse("Authorization status or redirect", "OAuthAuthorizeResponse"),
+          ...errorResponses
+        },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/{path}/~register": {
+      post: {
+        "operationId": "registerNode",
+        "security": bearerSecurity,
+        "parameters": [pathParameter],
+        "requestBody": { required: true, content: jsonContent("NodeInput") },
+        "responses": {
+          200: jsonResponse("Registered node", "RegistryNode"),
+          ...errorResponses
+        },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/{path}/~feedback": {
+      get: {
+        "operationId": "listFeedback",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, {
+          in: "query",
+          name: "hidden",
+          schema: { type: "string", enum: ["1"] }
+        }],
+        "responses": { 200: jsonResponse("Feedback list", "FeedbackList"), ...errorResponses },
+        "x-tool-bridge-greedy-path": true
+      },
+      post: {
+        "operationId": "submitFeedback",
+        "security": bearerSecurity,
+        "parameters": [pathParameter],
+        "requestBody": { required: true, content: jsonContent("FeedbackSubmitRequest") },
+        "responses": {
+          200: jsonResponse("Submitted feedback", "FeedbackSubmitResponse"),
+          ...errorResponses
+        },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/{path}/~feedback/{id}": {
+      get: {
+        "operationId": "getFeedback",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, { in: "path", name: "id", required: true, schema: { type: "string" } }],
+        "responses": { 200: jsonResponse("Feedback detail", "FeedbackDetail"), ...errorResponses },
+        "x-tool-bridge-greedy-path": true
+      },
+      post: {
+        "operationId": "voteFeedback",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, { in: "path", name: "id", required: true, schema: { type: "string" } }],
+        "requestBody": { required: true, content: jsonContent("FeedbackVoteRequest") },
+        "responses": { 200: jsonResponse("Updated feedback", "FeedbackView"), ...errorResponses },
+        "x-tool-bridge-greedy-path": true
+      },
+      delete: {
+        "operationId": "removeFeedback",
+        "security": bearerSecurity,
+        "parameters": [pathParameter, { in: "path", name: "id", required: true, schema: { type: "string" } }],
+        "responses": {
+          200: jsonResponse("Feedback removed", "FeedbackRemoveResponse"),
+          ...errorResponses
+        },
+        "x-tool-bridge-greedy-path": true
+      }
+    },
+    "/{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."
+        }],
+        "requestBody": {
+          required: true,
+          description: "Raw command arguments; there is no {tool, arguments} envelope.",
+          content: { "application/json": { schema: {} } }
+        },
+        "responses": {
+          200: {
+            description: "Raw JSON or Markdown according to Accept.",
+            content: {
+              "application/json": { schema: {} },
+              "text/markdown": { schema: { type: "string" } }
+            }
+          },
+          ...errorResponses
+        },
+        "x-tool-bridge-greedy-path": true
+      }
+    }
+  }
+};
+
 // ../app/src/paths.ts
 function scopeForCmd(mod, nodePath, cmd) {
   return mod.help(nodePath).cmds.find((c) => c.name === cmd);
@@ -36606,7 +37056,9 @@ function indexByParent(nodes) {
 }
 
 // ../app/src/routes/feedback.ts
-var feedbackJson = (value) => new Response(JSON.stringify(value), { headers: { "content-type": contentTypeFor("json") } });
+var feedbackJson = (schema, value) => new Response(JSON.stringify(schema.parse(value)), {
+  headers: { "content-type": contentTypeFor("json") }
+});
 async function handleFeedbackGet(c) {
   const target = splitFeedback(new URL(c.req.url).pathname);
   if (target === null || target.path === "") throw TBError.notFound("no such path");
@@ -36615,7 +37067,7 @@ async function handleFeedbackGet(c) {
   const fb = new FeedbackStore(c.get("store"));
   if (target.id !== void 0) {
     const e = await fb.get(target.path, target.id);
-    return feedbackJson({
+    return feedbackJson(feedbackDetailSchema, {
       id: e.id,
       path: target.path,
       title: e.title,
@@ -36629,7 +37081,7 @@ async function handleFeedbackGet(c) {
   }
   const views = await fb.listViews(target.path);
   const items = c.req.query("hidden") === "1" ? views : views.filter((v) => v.score > FEEDBACK_HIDE_SCORE);
-  return feedbackJson({ items });
+  return feedbackJson(feedbackListSchema, { items });
 }
 async function handleFeedbackPost(c, env) {
   const { searchSync } = env;
@@ -36651,23 +37103,32 @@ async function handleFeedbackPost(c, env) {
       await searchSync?.reconcileNodeQuietly(path, { feedback: entries, marker });
     });
     if (target.id !== void 0) {
-      const vote = body.vote;
-      if (vote !== "up" && vote !== "down" && vote !== "clear") {
+      const input2 = feedbackVoteRequestSchema.safeParse(body);
+      if (!input2.success) {
         throw new TBError("invalid_argument", `body.vote must be 'up' | 'down' | 'clear'`);
       }
-      return feedbackJson(await fb.vote(target.path, target.id, ctx.owner, vote));
+      return feedbackJson(
+        feedbackViewSchema,
+        await fb.vote(target.path, target.id, ctx.owner, input2.data.vote)
+      );
     }
-    if (typeof body.title !== "string" || typeof body.detail !== "string") {
+    const input = feedbackSubmitRequestSchema.safeParse(body);
+    if (!input.success) {
       throw new TBError("invalid_argument", "body must be { title: string, detail: string }");
     }
     await new NodeRegistryStore(store).resolve(target.path);
     const entry = await fb.submit(
       target.path,
-      { title: body.title, detail: body.detail },
+      input.data,
       ctx.owner,
       (/* @__PURE__ */ new Date()).toISOString()
     );
-    return feedbackJson({ id: entry.id, path: target.path, title: entry.title, at: entry.at });
+    return feedbackJson(feedbackSubmitResponseSchema, {
+      id: entry.id,
+      path: target.path,
+      title: entry.title,
+      at: entry.at
+    });
   } catch (error) {
     await searchSync?.abort(marker);
     throw error;
@@ -36693,12 +37154,12 @@ async function handleFeedbackDelete(c, env) {
     await searchSync?.abort(marker);
     throw error;
   }
-  return feedbackJson({ ok: true });
+  return feedbackJson(feedbackRemoveResponseSchema, { ok: true });
 }
 
 // ../app/src/responses.ts
 function tbErrorResponse(err) {
-  return new Response(JSON.stringify(err.toJSON()), {
+  return new Response(JSON.stringify(tbErrorBodySchema.parse(err.toJSON())), {
     status: err.httpStatus,
     headers: { "content-type": "application/json; charset=utf-8" }
   });
@@ -36735,7 +37196,7 @@ async function runHandler(fn) {
 }
 function renderHelp(model, rep) {
   if (rep === "json") {
-    return new Response(JSON.stringify(renderHelpJson(model)), {
+    return new Response(JSON.stringify(helpJsonSchema.parse(renderHelpJson(model))), {
       headers: { "content-type": contentTypeFor("json") }
     });
   }
@@ -36790,6 +37251,7 @@ function renderTreeDsl(tree) {
 }
 
 // ../app/src/federation.ts
+var SEARCH_REMAINING_MS_HEADER = "x-tb-search-remaining-ms";
 function remoteProtocolError(message) {
   return new TBError("unavailable", message, { retryable: false });
 }
@@ -36797,28 +37259,26 @@ function canonicalRemotePath(path, allowRoot) {
   if (path !== path.replace(/^\/+|\/+$/g, "")) {
     throw remoteProtocolError(`remote returned non-canonical path '${path}'`);
   }
+  if (path !== path.toLowerCase()) {
+    throw remoteProtocolError(`remote returned non-canonical path '${path}'`);
+  }
   const invalid = validatePath(path, { allowRoot });
   if (invalid !== null) throw remoteProtocolError(`remote returned invalid path '${path}'`);
   for (const segment of path === "" ? [] : path.split("/")) {
-    let decoded = segment;
-    for (let pass = 0; pass < 4; pass++) {
-      if (decoded === "." || decoded === ".." || decoded.startsWith("~") || decoded.includes("/") || decoded.includes("\\") || [...decoded].some((char) => {
-        const code = char.charCodeAt(0);
-        return code <= 31 || code === 127;
-      })) {
-        throw remoteProtocolError(`remote returned unsafe path segment '${segment}'`);
-      }
-      let next;
-      try {
-        next = decodeURIComponent(decoded);
-      } catch {
-        throw remoteProtocolError(`remote returned malformed encoded path '${path}'`);
-      }
-      if (next === decoded) break;
-      if (pass === 3) {
-        throw remoteProtocolError(`remote returned over-encoded path '${path}'`);
-      }
-      decoded = next;
+    if (segment === "." || segment === ".." || segment.startsWith("~") || segment.includes("\\") || segment.includes("?") || segment.includes("#") || [...segment].some((char) => {
+      const code = char.charCodeAt(0);
+      return code <= 31 || code === 127;
+    })) {
+      throw remoteProtocolError(`remote returned unsafe path segment '${segment}'`);
+    }
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      throw remoteProtocolError(`remote returned malformed encoded path '${path}'`);
+    }
+    if (decoded !== segment) {
+      throw remoteProtocolError(`remote returned non-canonical encoded path '${path}'`);
     }
   }
   return path;
@@ -36826,19 +37286,104 @@ function canonicalRemotePath(path, allowRoot) {
 function remotePathWithin(nodePath, commandPath) {
   return nodePath === "" || commandPath === nodePath || commandPath.startsWith(`${nodePath}/`);
 }
-function localizeRemoteEntry(mountPath, remoteParentPath, entry) {
-  const rel = canonicalRemotePath(entry.path, false);
-  const parent = rel.split("/").slice(0, -1).join("/");
-  if (parent !== remoteParentPath) {
-    throw remoteProtocolError(`remote ~tree child '${rel}' is not a direct descendant`);
+var CALLABLE_TREE_KINDS = /* @__PURE__ */ new Set(["device", "http", "mcp", "remote", "tool"]);
+function visibleRemotePath(ctx, path, kind) {
+  if (!check(ctx, path, "read").allow) return false;
+  return !CALLABLE_TREE_KINDS.has(kind) || check(ctx, path, "call").allow;
+}
+var RemotePathProjector = class {
+  constructor(mountPath) {
+    this.mountPath = mountPath;
+    const invalid = validatePath(mountPath);
+    if (invalid !== null) throw remoteProtocolError(`invalid remote mount path '${mountPath}'`);
+  }
+  mountPath;
+  childPath(localPath) {
+    if (localPath === this.mountPath) return "";
+    if (!localPath.startsWith(`${this.mountPath}/`)) {
+      throw remoteProtocolError(`local path '${localPath}' escapes remote mount '${this.mountPath}'`);
+    }
+    return localPath.slice(this.mountPath.length + 1);
+  }
+  localPath(childPath, allowRoot = true) {
+    const canonical = canonicalRemotePath(childPath, allowRoot);
+    return canonical === "" ? this.mountPath : `${this.mountPath}/${canonical}`;
+  }
+  childCommandPath(path) {
+    if (!path.startsWith("/") || path.startsWith("//")) {
+      throw remoteProtocolError(`remote ~help returned invalid command path '${path}'`);
+    }
+    return canonicalRemotePath(path.slice(1), false);
+  }
+  projectHelp(help, requestedLocalPath, ctx) {
+    const expectedChildPath = this.childPath(requestedLocalPath);
+    const nodeChildPath = canonicalRemotePath(help.node.path, expectedChildPath === "");
+    if (nodeChildPath !== expectedChildPath) {
+      throw remoteProtocolError(
+        `remote ~help path '${nodeChildPath}' does not match request '${expectedChildPath}'`
+      );
+    }
+    const nodePath = this.localPath(nodeChildPath, true);
+    const cmds = help.cmds.map((command) => {
+      const childCommandPath = this.childCommandPath(command.path);
+      if (!remotePathWithin(nodeChildPath, childCommandPath)) {
+        throw remoteProtocolError(`remote ~help command '${command.path}' escapes its node`);
+      }
+      return { ...command, path: `/${this.localPath(childCommandPath, false)}` };
+    });
+    const children = help.children?.map((child) => {
+      const childPath = canonicalRemotePath(child.path, false);
+      const parent = childPath.split("/").slice(0, -1).join("/");
+      if (parent !== nodeChildPath) {
+        throw remoteProtocolError(`remote ~help child '${childPath}' is not a direct descendant`);
+      }
+      return { ...child, path: this.localPath(childPath, false) };
+    }).filter((child) => ctx === void 0 || visibleRemotePath(ctx, child.path, child.kind));
+    return {
+      node: { ...help.node, path: nodePath },
+      cmds,
+      ...children === void 0 ? {} : { children },
+      ...help.feedback === void 0 ? {} : { feedback: help.feedback },
+      ...help.hint === void 0 ? {} : { hint: help.hint },
+      ...help.note === void 0 ? {} : { note: help.note }
+    };
   }
-  const out = {
-    path: `${mountPath}/${rel}`,
-    kind: entry.kind,
-    description: entry.description
-  };
-  if (entry.presence !== void 0) out.presence = entry.presence;
-  return out;
+  projectTree(tree, requestedLocalPath, ctx) {
+    const expectedChildPath = this.childPath(requestedLocalPath);
+    const rootChildPath = canonicalRemotePath(tree.path, expectedChildPath === "");
+    if (rootChildPath !== expectedChildPath) {
+      throw remoteProtocolError(
+        `remote ~tree path '${rootChildPath}' does not match request '${expectedChildPath}'`
+      );
+    }
+    const walk = (node, childPath) => {
+      const localPath = this.localPath(childPath, childPath === "");
+      const children = (node.children ?? []).map((child) => {
+        const canonical = canonicalRemotePath(child.path, false);
+        const parent = canonical.split("/").slice(0, -1).join("/");
+        if (parent !== childPath) {
+          throw remoteProtocolError(`remote ~tree child '${canonical}' is not a direct descendant`);
+        }
+        return walk(child, canonical);
+      }).filter((child) => visibleRemotePath(ctx, child.path, child.kind));
+      return {
+        path: localPath,
+        kind: node.kind,
+        description: node.description,
+        ...children.length === 0 ? {} : { children },
+        ...node.presence === void 0 ? {} : { presence: node.presence },
+        ...node.truncated === void 0 ? {} : { truncated: node.truncated }
+      };
+    };
+    return walk(tree, rootChildPath);
+  }
+};
+async function remotePathProjectorIfMatch(registry, treePath) {
+  const resolved = await registry.resolve(treePath).catch(() => null);
+  if (resolved === null || resolved.node.kind !== "remote" || resolved.node.config?.kind !== "remote") {
+    return null;
+  }
+  return new RemotePathProjector(resolved.node.path);
 }
 async function resolveRemoteSettings(state, base) {
   const runtime = await new RemoteAllowlistStore(state).hosts();
@@ -36861,6 +37406,17 @@ async function remotePassthroughIfMatch(c, ctx, registry, treePath, reservedTail
   }
   const requestPath = reservedTail === null ? treePath : `${treePath}/${reservedTail}`;
   const body = method === "POST" ? await c.req.text() : void 0;
+  const outboundHeaders = new Headers(headers);
+  const searchSettings = federatedSearchSettings(deps.remote);
+  const rawRemaining = outboundHeaders.get(SEARCH_REMAINING_MS_HEADER);
+  const requestedRemaining = rawRemaining !== null && /^\d+$/u.test(rawRemaining) ? Number(rawRemaining) : void 0;
+  const remainingMs = requestedRemaining !== void 0 && Number.isSafeInteger(requestedRemaining) && requestedRemaining > 0 ? Math.min(requestedRemaining, searchSettings.totalDeadlineMs) : void 0;
+  if (remainingMs !== void 0) {
+    outboundHeaders.set(
+      SEARCH_REMAINING_MS_HEADER,
+      String(Math.max(1, remainingMs - searchSettings.perHopReturnReserveMs))
+    );
+  }
   return await passthroughRemote({
     actor: { keyId: ctx.keyId, owner: ctx.owner, traceId: ctx.traceId },
     config: node.config,
@@ -36868,7 +37424,11 @@ async function remotePassthroughIfMatch(c, ctx, registry, treePath, reservedTail
     requestPath,
     method,
     ...body !== void 0 ? { body } : {},
-    headers,
+    headers: outboundHeaders,
+    ...remainingMs === void 0 ? {} : {
+      maxResponseBodyBytes: searchSettings.maxResponseBodyBytes,
+      signal: AbortSignal.timeout(remainingMs)
+    },
     secrets: deps.secrets,
     settings: await resolveRemoteSettings(deps.state, deps.remote),
     requestUrl: c.req.url
@@ -36892,15 +37452,14 @@ async function remoteTreeChildren(c, ctx, registry, treePath, deps) {
       retryable: resp.status >= 500
     });
   }
-  const remoteTree = await resp.json().catch(() => null);
-  if (remoteTree === null) {
+  const rawRemoteTree = await resp.json().catch(() => null);
+  const parsedRemoteTree = treeJsonSchema.safeParse(rawRemoteTree);
+  if (!parsedRemoteTree.success) {
     throw new TBError("unavailable", "remote ~tree returned invalid JSON", { retryable: false });
   }
-  const remotePath = canonicalRemotePath(remoteTree.path, true);
-  if (remotePath !== resolved.rest) {
-    throw remoteProtocolError(`remote ~tree path '${remotePath}' does not match request`);
-  }
-  return (remoteTree.children ?? []).map((child) => localizeRemoteEntry(resolved.node.path, remotePath, child));
+  const projector = new RemotePathProjector(resolved.node.path);
+  const projected = projector.projectTree(parsedRemoteTree.data, treePath, ctx);
+  return projected.children ?? [];
 }
 function assertRemoteConfigAllowed(config, settings) {
   if (config === null || typeof config !== "object") return;
@@ -36939,14 +37498,14 @@ async function authorizeToolNode(c, env, node, encryptionKey) {
     authRef: config.authRef,
     config: exported.oauth,
     encryptionKey,
-    fetcher: fetch,
+    fetcher: deps.providerOAuthFetch,
     nodePath: node.path,
     now: /* @__PURE__ */ new Date(),
     origin: deps.canonicalOrigin ?? new URL(c.req.url).origin,
     secrets: deps.secrets,
     store: deps.state
   });
-  return new Response(JSON.stringify(result), {
+  return new Response(JSON.stringify(oauthAuthorizeResponseSchema.parse(result)), {
     headers: { "content-type": contentTypeFor("json") }
   });
 }
@@ -36974,6 +37533,7 @@ async function handleRegister(c, env) {
   }
   await assertRegisterPath2(registry, ctx, body.path, "write", deps);
   assertSecretRefUse(ctx.scopes, body.config);
+  await assertMcpOAuthConfig(body.config, deps.secrets);
   await assertContextConfig(body.config, deps);
   await assertSkillhubConfig(body.config, deps);
   await assertToolConfig(body.config, deps, ctx, body.path);
@@ -36993,7 +37553,7 @@ async function handleRegister(c, env) {
   await invalidateProviderOAuth(store, body.path);
   await searchSync?.reconcileNodeQuietly(body.path, { marker });
   if (await refreshDynamicSearchNode(node, ctx, deps)) await searchSync?.abort(marker);
-  return new Response(JSON.stringify(node), {
+  return new Response(JSON.stringify(registryNodeSchema.parse(node)), {
     headers: { "content-type": contentTypeFor("json") }
   });
 }
@@ -37020,6 +37580,11 @@ async function handleAuthorize(c, env) {
   } catch {
     throw TBError.notFound("not found");
   }
+  const rawBody = await c.req.json().catch(() => ({}));
+  const body = oauthAuthorizeRequestSchema.safeParse(rawBody);
+  if (!body.success) {
+    throw new TBError("invalid_argument", "body only accepts optional redirectUri string");
+  }
   if (node.kind === "tool" && node.config?.kind === "tool") {
     return await authorizeToolNode(c, env, node, encKey);
   }
@@ -37029,17 +37594,18 @@ async function handleAuthorize(c, env) {
       `'${path}' \u65E2\u4E0D\u662F auth:'oauth' \u7684 mcp \u6302\u8F7D,\u4E5F\u4E0D\u662F\u58F0\u660E\u4E86 oauth \u7684 tool \u6302\u8F7D`
     );
   }
-  const body = await c.req.json().catch(() => null);
-  const redirectUri = body !== null && typeof body.redirectUri === "string" ? body.redirectUri : void 0;
+  const redirectUri = body.data.redirectUri;
   const result = await startMcpAuthorization({
     store,
     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(result), {
+  return new Response(JSON.stringify(oauthAuthorizeResponseSchema.parse(result)), {
     headers: { "content-type": contentTypeFor("json") }
   });
 }
@@ -37141,16 +37707,6 @@ function uploadId(body) {
   }
   return body.uploadId;
 }
-function origin(c, canonicalOrigin) {
-  let url2;
-  try {
-    url2 = new URL(canonicalOrigin ?? c.req.url);
-  } catch {
-    throw new TBError("unavailable", "request origin is invalid", { retryable: false });
-  }
-  if (url2.protocol !== "https:" && url2.protocol !== "http:" || url2.username !== "" || url2.password !== "") throw new TBError("unavailable", "request origin is invalid", { retryable: false });
-  return url2.origin;
-}
 function registerStoreCapabilityRoutes(app, deps) {
   app.post("/system/store/create_upload", async (c, next) => {
     if (c.req.header(STORE_CALL_CAPABILITY_HEADER) === void 0) return await next();
@@ -37162,7 +37718,7 @@ function registerStoreCapabilityRoutes(app, deps) {
         deps,
         body,
         capability,
-        origin(c, deps.canonicalOrigin)
+        resolveStoreRequestOrigin(c.req.url, deps.canonicalOrigin)
       );
       return c.json(result);
     });
@@ -37262,7 +37818,7 @@ async function finishToolAuthorization(opts) {
       codeVerifier: opts.verifier,
       config: exported.oauth,
       encryptionKey: opts.encryptionKey,
-      fetcher: fetch,
+      fetcher: opts.deps.providerOAuthFetch,
       nodePath: opts.node.path,
       now: /* @__PURE__ */ new Date(),
       origin: opts.origin,
@@ -37279,21 +37835,23 @@ function registerPublicRoutes(app, env) {
   app.get("/healthz", async (c) => {
     const catalog = deps.pluginCatalog;
     const digest = await env.pluginCatalogDigest();
-    return c.json({
+    return c.json(healthResponseSchema.parse({
       healthy: true,
       version: deps.version,
       ...catalog !== void 0 && digest !== void 0 ? { catalog: { count: Object.keys(catalog).length, digest } } : {}
-    });
+    }));
   });
-  app.get("/livez", (c) => c.json({ live: true }));
+  app.get("/livez", (c) => c.json(livenessResponseSchema.parse({ live: true })));
   app.get("/readyz", async (c) => {
     const probe = deps.readiness;
-    if (probe === void 0) return c.json({ checks: {}, ready: true });
+    if (probe === void 0) {
+      return c.json(readinessResponseSchema.parse({ checks: {}, ready: true }));
+    }
     try {
-      const report = await probe();
+      const report = readinessResponseSchema.parse(await probe());
       return c.json(report, report.ready ? 200 : 503);
     } catch {
-      return c.json({ checks: {}, ready: false }, 503);
+      return c.json(readinessResponseSchema.parse({ checks: {}, ready: false }), 503);
     }
   });
   app.get(
@@ -37388,15 +37946,25 @@ function registerPublicRoutes(app, env) {
       if (node.kind !== "mcp" || node.config?.kind !== "mcp" || node.config.auth !== "oauth") {
         return renderOAuthCallbackHtml(false, "target node is not an OAuth-backed mount");
       }
+      const currentClient = node.config.oauthClient;
+      if (payload.o === void 0 !== (currentClient === void 0) || payload.o !== void 0 && (currentClient?.clientId !== payload.o.i || currentClient.clientSecretRef !== payload.o.r)) {
+        return renderOAuthCallbackHtml(
+          false,
+          "OAuth client configuration changed; restart authorization"
+        );
+      }
       try {
         await finishMcpAuthorization({
           store: deps.state,
           encryptionKey: encKey,
           nodePath: payload.p,
           serverUrl: node.config.url,
+          secrets: deps.secrets,
           origin: deps.canonicalOrigin ?? new URL(c.req.url).origin,
           code,
           codeVerifier: payload.v,
+          ...q.iss !== void 0 ? { authorizationResponseIssuer: q.iss } : {},
+          ...node.config.oauthClient !== void 0 ? { oauthClient: node.config.oauthClient } : {},
           // 本地回调通道(CLI --local):兑换必须复用授权时的 redirect_uri。
           ...payload.r !== void 0 ? { redirectUri: payload.r } : {}
         });
@@ -37409,7 +37977,1505 @@ function registerPublicRoutes(app, env) {
   );
 }
 
+// ../app/src/search/federatedSession.ts
+var FEDERATED_SEARCH_HANDLE_PREFIX = "fsc1_";
+var FEDERATED_SEARCH_HANDLE_RANDOM_BYTES = 24;
+var FEDERATED_SEARCH_HANDLE_LENGTH = 37;
+var FEDERATED_SEARCH_SESSION_KEY_PREFIX = "fsearch:session:v1:";
+var FEDERATED_SEARCH_QUOTA_KEY = "fsearch:quota:v1";
+var HANDLE_PATTERN = /^fsc1_[A-Za-z0-9_-]{32}$/;
+var MAX_SAFE_JSON_DEPTH = 64;
+var MAX_SAFE_JSON_NODES = 1e4;
+var DEFAULT_MAX_RECORD_BYTES = 1024 * 1024;
+var DEFAULT_MAX_BYTES_GLOBAL = 128 * 1024 * 1024;
+var DEFAULT_MAX_BYTES_PER_ACTOR = 32 * 1024 * 1024;
+var DEFAULT_MAX_BYTES_PER_SESSION = 8 * 1024 * 1024;
+var DEFAULT_MAX_GENERATIONS_PER_SESSION = 1024;
+var DEFAULT_MAX_SESSIONS_GLOBAL = 256;
+var DEFAULT_MAX_SESSIONS_PER_ACTOR = 64;
+var QUOTA_CAS_ATTEMPTS = 32;
+var FORBIDDEN_STATE_KEYS = /* @__PURE__ */ new Set([
+  "$schema",
+  "authorization",
+  "baseurl",
+  "credential",
+  "inputschema",
+  "outputschema",
+  "schema",
+  "secret",
+  "sk",
+  "token"
+]);
+function sessionUnavailable(message) {
+  return new TBError("unavailable", message, { retryable: false });
+}
+function invalidSession() {
+  return new TBError("invalid_argument", "federated search session is invalid or expired", {
+    retryable: false
+  });
+}
+function corruptSession() {
+  return new TBError("internal", "federated search session state is corrupt", {
+    retryable: false
+  });
+}
+function isPlainObject3(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(value, expected) {
+  const actual = Object.keys(value).sort();
+  const sortedExpected = [...expected].sort();
+  return actual.length === sortedExpected.length && actual.every((key, index) => key === sortedExpected[index]);
+}
+function validOpaque(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 256 && !/[\0\r\n]/u.test(value);
+}
+function validExpiry(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function normalizedStateKey(key) {
+  return key.replaceAll("-", "").replaceAll("_", "").toLowerCase();
+}
+function safeStateValue(value, state, depth = 0) {
+  state.nodes++;
+  if (state.nodes > MAX_SAFE_JSON_NODES || depth > MAX_SAFE_JSON_DEPTH) {
+    throw new Error("federated search session value exceeds structural limits");
+  }
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("non-finite number");
+    return value;
+  }
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((item) => safeStateValue(item, state, depth + 1)));
+  }
+  if (!isPlainObject3(value)) throw new Error("non-JSON value");
+  const clone = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (FORBIDDEN_STATE_KEYS.has(normalizedStateKey(key))) {
+      throw new Error(`forbidden state field '${key}'`);
+    }
+    clone[key] = safeStateValue(item, state, depth + 1);
+  }
+  return Object.freeze(clone);
+}
+function parseRecord(value) {
+  if (!isPlainObject3(value) || !hasExactKeys(value, [
+    "actorKeyId",
+    "excludedStatuses",
+    "expiresAt",
+    "federationPolicy",
+    "generation",
+    "nextHandle",
+    "page",
+    "rankingVersion",
+    "requestDigest",
+    "revision",
+    "sessionId",
+    "sourceContinuations",
+    "topologyDigest"
+  ])) {
+    throw corruptSession();
+  }
+  if (value.revision !== 0 || !validOpaque(value.sessionId) || !validOpaque(value.actorKeyId) || !validOpaque(value.requestDigest) || !validOpaque(value.rankingVersion) || !validOpaque(value.topologyDigest) || !validExpiry(value.expiresAt) || !Number.isSafeInteger(value.generation) || value.generation < 0 || value.nextHandle !== null && (typeof value.nextHandle !== "string" || !HANDLE_PATTERN.test(value.nextHandle))) {
+    throw corruptSession();
+  }
+  try {
+    const state = { nodes: 0 };
+    return Object.freeze({
+      actorKeyId: value.actorKeyId,
+      excludedStatuses: safeStateValue(value.excludedStatuses, state),
+      expiresAt: value.expiresAt,
+      federationPolicy: safeStateValue(value.federationPolicy, state),
+      generation: value.generation,
+      nextHandle: value.nextHandle,
+      page: safeStateValue(value.page, state),
+      rankingVersion: value.rankingVersion,
+      requestDigest: value.requestDigest,
+      revision: 0,
+      sessionId: value.sessionId,
+      sourceContinuations: safeStateValue(value.sourceContinuations, state),
+      topologyDigest: value.topologyDigest
+    });
+  } catch (error) {
+    if (error instanceof TBError) throw error;
+    throw corruptSession();
+  }
+}
+function parseCreate(handle, input) {
+  try {
+    return parseRecord({
+      ...input,
+      revision: 0,
+      sessionId: input.sessionId ?? handle
+    });
+  } catch {
+    throw new TBError("invalid_argument", "federated search session input is invalid", {
+      retryable: false
+    });
+  }
+}
+function parseQuotaRecord(value) {
+  if (!isPlainObject3(value) || !hasExactKeys(value, ["revision", "sessions"])) {
+    throw corruptSession();
+  }
+  if (!Number.isSafeInteger(value.revision) || value.revision < 0 || !Array.isArray(value.sessions)) {
+    throw corruptSession();
+  }
+  const sessions = value.sessions.map((item) => {
+    if (!isPlainObject3(item) || !hasExactKeys(item, [
+      "actorKeyId",
+      "bytes",
+      "expiresAt",
+      "generation",
+      "generationBytes",
+      "generationId",
+      "id"
+    ]) || !validOpaque(item.actorKeyId) || !validExpiry(item.expiresAt) || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || !Number.isSafeInteger(item.generation) || item.generation < 0 || !Number.isSafeInteger(item.generationBytes) || item.generationBytes < 1 || typeof item.generationId !== "string" || !/^[0-9a-f]{64}$/u.test(item.generationId) || typeof item.id !== "string" || !/^[0-9a-f]{64}$/u.test(item.id)) {
+      throw corruptSession();
+    }
+    return {
+      actorKeyId: item.actorKeyId,
+      bytes: item.bytes,
+      expiresAt: item.expiresAt,
+      generation: item.generation,
+      generationBytes: item.generationBytes,
+      generationId: item.generationId,
+      id: item.id
+    };
+  });
+  return { revision: value.revision, sessions };
+}
+function isFederatedSearchSessionHandle(value) {
+  return typeof value === "string" && value.length === FEDERATED_SEARCH_HANDLE_LENGTH && HANDLE_PATTERN.test(value);
+}
+async function federatedSearchSessionStateKey(handle) {
+  if (!isFederatedSearchSessionHandle(handle)) throw invalidSession();
+  return FEDERATED_SEARCH_SESSION_KEY_PREFIX + await sha256Hex(handle);
+}
+var FederatedSearchSessionStore = class {
+  constructor(state, opts = {}) {
+    this.state = state;
+    if (state.compareAndSwap === void 0) {
+      throw sessionUnavailable("federated search sessions require StateStore.compareAndSwap");
+    }
+    this.cas = state.compareAndSwap.bind(state);
+    this.maxBytesGlobal = opts.maxBytesGlobal ?? DEFAULT_MAX_BYTES_GLOBAL;
+    this.maxBytesPerActor = opts.maxBytesPerActor ?? DEFAULT_MAX_BYTES_PER_ACTOR;
+    this.maxBytesPerSession = opts.maxBytesPerSession ?? DEFAULT_MAX_BYTES_PER_SESSION;
+    this.maxGenerationsPerSession = opts.maxGenerationsPerSession ?? DEFAULT_MAX_GENERATIONS_PER_SESSION;
+    this.maxRecordBytes = opts.maxRecordBytes ?? DEFAULT_MAX_RECORD_BYTES;
+    this.maxSessionsGlobal = opts.maxSessionsGlobal ?? DEFAULT_MAX_SESSIONS_GLOBAL;
+    this.maxSessionsPerActor = opts.maxSessionsPerActor ?? DEFAULT_MAX_SESSIONS_PER_ACTOR;
+    this.now = opts.now ?? (() => Date.now());
+    this.randomBytes = opts.randomBytes ?? ((length) => crypto.getRandomValues(new Uint8Array(length)));
+  }
+  state;
+  cas;
+  now;
+  randomBytes;
+  maxBytesGlobal;
+  maxBytesPerActor;
+  maxBytesPerSession;
+  maxGenerationsPerSession;
+  maxRecordBytes;
+  maxSessionsGlobal;
+  maxSessionsPerActor;
+  async cleanupExpiredSessionRows() {
+    const page = await this.state.list(FEDERATED_SEARCH_SESSION_KEY_PREFIX, { limit: 32 });
+    for (const item of page.items) {
+      let record2;
+      try {
+        record2 = parseRecord(item.value);
+      } catch {
+        continue;
+      }
+      if (Date.parse(record2.expiresAt) <= this.now()) {
+        await this.state.delete(item.key).catch(() => {
+        });
+      }
+    }
+  }
+  async reserveQuota(handle, record2, recordBytes) {
+    const id = await sha256Hex(record2.sessionId);
+    const generationId = await sha256Hex(handle);
+    for (let attempt2 = 0; attempt2 < QUOTA_CAS_ATTEMPTS; attempt2++) {
+      const raw = await this.state.get(FEDERATED_SEARCH_QUOTA_KEY);
+      const current = raw === null ? { revision: 0, sessions: [] } : parseQuotaRecord(raw);
+      const active = current.sessions.filter((entry) => Date.parse(entry.expiresAt) > this.now());
+      const existing = active.find((entry) => entry.id === id);
+      let nextEntry;
+      if (existing !== void 0) {
+        if (existing.actorKeyId !== record2.actorKeyId || existing.expiresAt !== record2.expiresAt) throw invalidSession();
+        if (record2.generation === existing.generation) {
+          if (existing.generationId !== generationId || existing.generationBytes !== recordBytes) throw invalidSession();
+          return;
+        }
+        if (record2.generation !== existing.generation + 1 || generationId === existing.generationId) throw invalidSession();
+        nextEntry = {
+          ...existing,
+          bytes: existing.bytes + recordBytes,
+          generation: record2.generation,
+          generationBytes: recordBytes,
+          generationId
+        };
+      } else {
+        if (record2.generation !== 0) throw invalidSession();
+        nextEntry = {
+          actorKeyId: record2.actorKeyId,
+          bytes: recordBytes,
+          expiresAt: record2.expiresAt,
+          generation: 0,
+          generationBytes: recordBytes,
+          generationId,
+          id
+        };
+      }
+      const actorCount = active.filter((entry) => entry.actorKeyId === record2.actorKeyId).length;
+      const globalBytes = active.reduce((total, entry) => total + entry.bytes, 0);
+      const actorBytes = active.filter((entry) => entry.actorKeyId === record2.actorKeyId).reduce((total, entry) => total + entry.bytes, 0);
+      const priorBytes = existing?.bytes ?? 0;
+      if (record2.generation >= this.maxGenerationsPerSession || nextEntry.bytes > this.maxBytesPerSession) {
+        throw new TBError("rate_limited", "federated search session chain quota exceeded", {
+          retryable: false
+        });
+      }
+      if (existing === void 0 && active.length >= this.maxSessionsGlobal || existing === void 0 && actorCount >= this.maxSessionsPerActor || globalBytes - priorBytes + nextEntry.bytes > this.maxBytesGlobal || actorBytes - priorBytes + nextEntry.bytes > this.maxBytesPerActor) {
+        throw new TBError("rate_limited", "federated search session quota exceeded", {
+          retryable: true
+        });
+      }
+      const next = {
+        revision: raw === null ? 0 : current.revision + 1,
+        sessions: [
+          ...active.filter((entry) => entry.id !== id),
+          nextEntry
+        ]
+      };
+      if (await this.cas(
+        FEDERATED_SEARCH_QUOTA_KEY,
+        raw === null ? null : current.revision,
+        next
+      )) return;
+    }
+    throw new TBError("unavailable", "federated search session quota is busy", {
+      retryable: true
+    });
+  }
+  issueHandle() {
+    const bytes = this.randomBytes(FEDERATED_SEARCH_HANDLE_RANDOM_BYTES);
+    if (!(bytes instanceof Uint8Array) || bytes.length !== FEDERATED_SEARCH_HANDLE_RANDOM_BYTES) {
+      throw sessionUnavailable("federated search session randomness is unavailable");
+    }
+    const handle = FEDERATED_SEARCH_HANDLE_PREFIX + base64urlEncode(bytes);
+    if (!isFederatedSearchSessionHandle(handle)) {
+      throw sessionUnavailable("federated search session randomness is invalid");
+    }
+    return handle;
+  }
+  async create(handle, input) {
+    const key = await federatedSearchSessionStateKey(handle);
+    const record2 = parseCreate(handle, input);
+    if (Date.parse(record2.expiresAt) <= this.now()) throw invalidSession();
+    const recordBytes = new TextEncoder().encode(JSON.stringify(record2)).length;
+    if (recordBytes > this.maxRecordBytes) {
+      throw new TBError("rate_limited", "federated search session record is too large", {
+        retryable: false
+      });
+    }
+    if (await this.state.get(key) !== null) return await this.read(handle, input);
+    if (record2.generation === 0) await this.cleanupExpiredSessionRows();
+    await this.reserveQuota(handle, record2, recordBytes);
+    if (await this.cas(key, null, record2)) {
+      return record2;
+    }
+    return await this.read(handle, input);
+  }
+  async createNew(input) {
+    const handle = this.issueHandle();
+    return { handle, record: await this.create(handle, input) };
+  }
+  async read(handle, binding) {
+    if (!validOpaque(binding.actorKeyId) || !validOpaque(binding.requestDigest)) {
+      throw invalidSession();
+    }
+    const raw = await this.state.get(await federatedSearchSessionStateKey(handle));
+    if (raw === null) throw invalidSession();
+    const record2 = parseRecord(raw);
+    if (Date.parse(record2.expiresAt) <= this.now()) {
+      await this.state.delete(await federatedSearchSessionStateKey(handle)).catch(() => {
+      });
+      throw invalidSession();
+    }
+    if (record2.actorKeyId !== binding.actorKeyId || record2.requestDigest !== binding.requestDigest) {
+      throw invalidSession();
+    }
+    return record2;
+  }
+};
+
+// ../app/src/search/localSearch.ts
+function normalizedEffect(effect) {
+  return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
+}
+function projectSearchTool(tool, detail) {
+  if (detail === "full") return tool;
+  const compact = { ...tool };
+  delete compact.inputSchema;
+  delete compact.outputSchema;
+  if (compact.description !== void 0) {
+    const encoder = new TextEncoder();
+    if (encoder.encode(compact.description).length > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) {
+      let description = "";
+      let bytes = 0;
+      for (const char of compact.description) {
+        const size = encoder.encode(char).length;
+        if (bytes + size > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) break;
+        description += char;
+        bytes += size;
+      }
+      compact.description = description;
+    }
+  }
+  return compact;
+}
+async function executeLocalSearch(deps, request) {
+  const { ctx, search, searchSync, state } = deps;
+  const query = request.query;
+  const wireOpts = request.opts ?? {};
+  const detail = wireOpts.detail ?? "compact";
+  const matching = wireOpts.matching ?? "best";
+  const mode = wireOpts.mode ?? "keyword";
+  const limit = normalizeToolSearchLimit(wireOpts.limit);
+  const constraints = normalizeToolSearchOptions({
+    ...wireOpts.effects === void 0 ? {} : { effects: wireOpts.effects },
+    matching,
+    ...wireOpts.minCoverage === void 0 ? {} : { minCoverage: wireOpts.minCoverage },
+    ...wireOpts.pathPrefix === void 0 ? {} : { pathPrefix: wireOpts.pathPrefix }
+  });
+  const indexOptions = { mode, ...constraints };
+  await searchSync?.ensureReady();
+  const registry = new NodeRegistryStore(state);
+  const selected = [];
+  const workLimit = Math.min(
+    TOOL_SEARCH_WORK_LIMIT,
+    Math.max(TOOL_SEARCH_BATCH_LIMIT, limit * 2)
+  );
+  let scanCursor = wireOpts.cursor;
+  let responseCursor;
+  let responseCandidate;
+  let visibleCoverage;
+  let scanned = 0;
+  let stopped = false;
+  while (!stopped && selected.length < limit && scanned < workLimit) {
+    const batchLimit = Math.min(TOOL_SEARCH_BATCH_LIMIT, workLimit - scanned);
+    const page = await search.search(query, {
+      ...indexOptions,
+      limit: batchLimit,
+      ...scanCursor === void 0 ? {} : { cursor: scanCursor }
+    });
+    if (page.items.length === 0) {
+      responseCursor = page.cursor;
+      break;
+    }
+    const nodes = await registry.getMany(page.items.map((candidate) => candidate.path));
+    let lastCandidateInVisibleBand;
+    for (const [index, candidate] of page.items.entries()) {
+      if (matching === "best" && visibleCoverage !== void 0 && candidate.coverage !== visibleCoverage) {
+        responseCandidate = lastCandidateInVisibleBand;
+        responseCursor = responseCandidate === void 0 ? scanCursor : void 0;
+        stopped = true;
+        break;
+      }
+      scanned++;
+      lastCandidateInVisibleBand = candidate;
+      if (!check(ctx, candidate.path, "read").allow || !check(ctx, candidate.path, "call").allow) {
+        continue;
+      }
+      const node = nodes.get(candidate.path);
+      if (node === void 0 || node.kind !== "mcp" && node.kind !== "http" && node.kind !== "tool" || node.config?.kind !== node.kind || virtualizeTools(node.virtualize, [{ name: candidate.name }]).exposed.length === 0) {
+        continue;
+      }
+      visibleCoverage ??= candidate.coverage;
+      selected.push({ candidate, node });
+      if (selected.length === limit) {
+        const hasUnscanned = index < page.items.length - 1 || page.cursor !== void 0;
+        responseCandidate = hasUnscanned ? candidate : void 0;
+        responseCursor = void 0;
+        stopped = true;
+        break;
+      }
+    }
+    if (stopped) break;
+    responseCursor = page.cursor;
+    if (page.cursor === void 0) break;
+    scanCursor = page.cursor;
+  }
+  const canonicalTools = await canonicalSearchTools(state, selected.map((item) => item.node));
+  const requestedEffects = constraints.effects === void 0 ? void 0 : new Set(constraints.effects);
+  const items = [];
+  let pageBytes = 0;
+  for (const [index, selectedItem] of selected.entries()) {
+    const raw = canonicalTools.get(selectedItem.candidate.path)?.find((tool2) => tool2.name === selectedItem.candidate.name);
+    if (raw === void 0) continue;
+    const tool = virtualizeTools(selectedItem.node.virtualize, [raw]).exposed[0];
+    if (tool === void 0) continue;
+    if (requestedEffects !== void 0 && !requestedEffects.has(normalizedEffect(tool.effect))) {
+      continue;
+    }
+    const item = {
+      path: selectedItem.candidate.path,
+      relevance: {
+        coverage: selectedItem.candidate.coverage,
+        matchedTermCount: selectedItem.candidate.matchedTermCount,
+        rankingVersion: "keyword-v2",
+        totalTermCount: selectedItem.candidate.totalTermCount
+      },
+      tool: projectSearchTool(tool, detail)
+    };
+    const itemBytes = new TextEncoder().encode(JSON.stringify(item)).length;
+    if (pageBytes + itemBytes > TOOL_SEARCH_PAGE_BYTES) {
+      if (items.length === 0) {
+        throw new TBError("internal", "\u5DE5\u5177\u641C\u7D22\u9875\u9762\u5B57\u8282\u9884\u7B97\u65E0\u6CD5\u5BB9\u7EB3\u9996\u4E2A\u7ED3\u679C");
+      }
+      responseCandidate = selected[index - 1]?.candidate;
+      responseCursor = void 0;
+      break;
+    }
+    items.push(item);
+    pageBytes += itemBytes;
+  }
+  if (responseCandidate !== void 0) {
+    responseCursor = await search.cursorFor(query, responseCandidate, mode);
+  }
+  if (items.length === 0) responseCursor = void 0;
+  return responseCursor === void 0 ? { items } : { items, cursor: responseCursor };
+}
+
+// ../app/src/search/federatedSearch.ts
+var HEADER_REMAINING_MS = "x-tb-search-remaining-ms";
+var HEADER_SESSION_TTL_MS = "x-tb-search-session-ttl-ms";
+var HEADER_SOURCE_BUDGET = "x-tb-search-source-budget";
+var HEADER_VALIDATE_SNAPSHOT = "x-tb-search-validate-snapshot";
+var HEADER_VIA = "x-tb-via";
+var HEADER_WANT_SNAPSHOT = "x-tb-search-want-snapshot";
+function clampHeader(value, local) {
+  if (value === null || !/^\d+$/u.test(value)) return local;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? Math.min(parsed, local) : local;
+}
+function isPrefix(prefix, path) {
+  return prefix === "" || prefix === path || path.startsWith(`${prefix}/`);
+}
+function controlledStatus(error) {
+  if (error instanceof TBError) {
+    if (error.message.includes("\u73AF")) return "cycle";
+    if (error.message.includes("\u8DF3\u6570")) return "hop_limit";
+    if (error.message.includes("aborted")) return "timed_out";
+    if (error.message.includes("work budget")) return "budget_exhausted";
+  }
+  return "unavailable";
+}
+function retryableContinuationError() {
+  return new TBError("unavailable", "federated search continuation source unavailable", {
+    retryable: true
+  });
+}
+function invalidContinuation() {
+  return new TBError("invalid_argument", "federated search cursor no longer matches topology", {
+    retryable: false
+  });
+}
+function continuationSourceError(error) {
+  if (error instanceof TBError) {
+    if (error.code === "invalid_argument") return error;
+    if (error.message.includes("source work budget exhausted")) return invalidContinuation();
+  }
+  return retryableContinuationError();
+}
+function compactItem(item) {
+  const tool = { ...item.tool };
+  delete tool.inputSchema;
+  delete tool.outputSchema;
+  if (tool.description !== void 0) {
+    const encoder = new TextEncoder();
+    if (encoder.encode(tool.description).length > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) {
+      let description = "";
+      let bytes = 0;
+      for (const char of tool.description) {
+        const size = encoder.encode(char).length;
+        if (bytes + size > TOOL_SEARCH_DESCRIPTION_BYTES_MAX) break;
+        description += char;
+        bytes += size;
+      }
+      tool.description = description;
+    }
+  }
+  return { ...item, tool };
+}
+function normalizedEffect2(effect) {
+  return effect === "read" || effect === "write" || effect === "destructive" ? effect : "unknown";
+}
+function requestConstraints(request) {
+  return normalizeToolSearchOptions({
+    ...request.opts?.effects === void 0 ? {} : { effects: request.opts.effects },
+    matching: request.opts?.matching ?? "best",
+    ...request.opts?.minCoverage === void 0 ? {} : { minCoverage: request.opts.minCoverage },
+    ...request.opts?.pathPrefix === void 0 ? {} : { pathPrefix: request.opts.pathPrefix }
+  });
+}
+function assertHardResultConstraints(item, constraints) {
+  const effects = constraints.effects === void 0 ? void 0 : new Set(constraints.effects);
+  if (constraints.pathPrefix !== void 0 && !isPrefix(constraints.pathPrefix, item.path) || constraints.minCoverage !== void 0 && item.relevance.coverage < constraints.minCoverage || effects !== void 0 && !effects.has(normalizedEffect2(item.tool.effect))) {
+    throw new TBError("unavailable", "remote search violated a hard result constraint", {
+      retryable: false
+    });
+  }
+}
+function sourceStatusKey(value) {
+  return `${value.path}\0${value.status}`;
+}
+function mergeStatuses(...groups) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of groups.flat()) {
+    const key = sourceStatusKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out.sort((left, right) => left.path.localeCompare(right.path) || left.status.localeCompare(right.status));
+}
+function responseHasMore(sources) {
+  return sources.some((source) => source.pending !== void 0 || !source.done);
+}
+function serializableSources(sources) {
+  return sources.map((source) => ({
+    balanceCount: source.balanceCount,
+    ...source.balanceCoverage === void 0 ? {} : { balanceCoverage: source.balanceCoverage },
+    budget: source.budget,
+    done: source.done,
+    ...source.excluded === void 0 ? {} : { excluded: source.excluded },
+    kind: source.kind,
+    path: source.path,
+    ...source.cursor === void 0 ? {} : { cursor: source.cursor },
+    ...source.nextCursor === void 0 ? {} : { nextCursor: source.nextCursor },
+    ...source.pending === void 0 ? {} : { pending: compactItem(source.pending) },
+    ...source.validationCursor === void 0 ? {} : { validationCursor: source.validationCursor }
+  }));
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const object2 = value;
+  return `{${Object.keys(object2).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object2[key])}`).join(",")}}`;
+}
+function sameJson(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+function assertNextRecord(current, next, topology) {
+  if (next.topologyDigest !== topology || next.rankingVersion !== TOOL_SEARCH_RANKING_VERSION || next.sessionId !== current.sessionId || next.generation !== current.generation + 1 || next.expiresAt !== current.expiresAt || !sameJson(next.federationPolicy, current.federationPolicy)) {
+    throw invalidContinuation();
+  }
+}
+function assertCachedPage(computed, cached) {
+  if (!sameJson(computed.page, cached.page) || !sameJson(computed.excluded, cached.excludedStatuses) || !sameJson(serializableSources(computed.sources), cached.sourceContinuations)) {
+    throw invalidContinuation();
+  }
+}
+function requestForDigest(request, limit) {
+  const opts = request.opts ?? {};
+  return {
+    query: request.query,
+    opts: {
+      effects: opts.effects ?? null,
+      federation: "recursive",
+      limit,
+      matching: opts.matching ?? "best",
+      minCoverage: opts.minCoverage ?? null,
+      mode: opts.mode ?? "keyword",
+      pathPrefix: opts.pathPrefix ?? null
+    }
+  };
+}
+async function topologyDigest(nodes, includeLocal, localRevision, remotePolicy) {
+  return await sha256Hex(canonicalJson({
+    local: includeLocal,
+    localRevision,
+    nodes: nodes.map((node) => ({
+      kind: node.kind,
+      path: node.path,
+      remote: node.config?.kind === "remote" ? { baseUrl: node.config.baseUrl, skRef: node.config.skRef ?? null } : null,
+      updatedAt: node.updatedAt ?? "",
+      virtualize: node.virtualize ?? null
+    })),
+    remotePolicy
+  }));
+}
+function directRemoteNodes(nodes) {
+  const remotes = nodes.filter((node) => node.kind === "remote" && node.config?.kind === "remote").sort((left, right) => left.path.localeCompare(right.path));
+  return remotes.filter((node) => !remotes.some((parent) => parent.path !== node.path && isPrefix(parent.path, node.path)));
+}
+function childPrefixFor(mount, pathPrefix) {
+  if (pathPrefix === void 0) return { eligible: true };
+  if (isPrefix(mount, pathPrefix)) {
+    const child = new RemotePathProjector(mount).childPath(pathPrefix);
+    return { eligible: true, ...child === "" ? {} : { pathPrefix: child } };
+  }
+  return { eligible: isPrefix(pathPrefix, mount) };
+}
+function localEligible(remotes, pathPrefix) {
+  return pathPrefix === void 0 || !remotes.some((node) => isPrefix(node.path, pathPrefix));
+}
+async function mapLimit(values, concurrency, fn) {
+  const results = new Array(values.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (next < values.length) {
+      const index = next++;
+      results[index] = await fn(values[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+function deadlineSignal(deadline) {
+  return AbortSignal.timeout(Math.max(1, Math.floor(deadline - Date.now())));
+}
+function federatedHeaders(inbound, remainingMs, sourceBudget, sessionTtlMs) {
+  const headers = new Headers();
+  headers.set("accept", "application/json");
+  headers.set("content-type", "application/json");
+  const via = inbound.get(HEADER_VIA);
+  if (via !== null) headers.set(HEADER_VIA, via);
+  headers.set(HEADER_REMAINING_MS, String(Math.max(1, Math.floor(remainingMs))));
+  headers.set(HEADER_SESSION_TTL_MS, String(Math.max(1, Math.floor(sessionTtlMs))));
+  headers.set(HEADER_SOURCE_BUDGET, String(Math.max(1, Math.floor(sourceBudget))));
+  headers.set(HEADER_WANT_SNAPSHOT, "1");
+  return headers;
+}
+function projectChildPage(mount, page, totalTermCount, ctx, request) {
+  const projector = new RemotePathProjector(mount);
+  const constraints = requestConstraints(request);
+  const items = page.items.map((item) => {
+    if (item.relevance.rankingVersion !== TOOL_SEARCH_RANKING_VERSION || item.relevance.totalTermCount !== totalTermCount || item.relevance.matchedTermCount < 1 || item.relevance.matchedTermCount > totalTermCount || item.relevance.coverage !== item.relevance.matchedTermCount / totalTermCount) {
+      throw new TBError("unavailable", "remote search returned incompatible relevance evidence", {
+        retryable: false
+      });
+    }
+    const path = projector.localPath(item.path, false);
+    const sourcePath = projector.localPath(item.source?.path ?? "", true);
+    if (item.tool.name.includes("/")) {
+      throw new TBError("unavailable", "remote search returned an unsafe tool name", {
+        retryable: false
+      });
+    }
+    try {
+      if (canonicalRemotePath(item.tool.name, false) !== item.tool.name.toLowerCase()) {
+        throw new Error("non-canonical");
+      }
+    } catch {
+      throw new TBError("unavailable", "remote search returned an unsafe tool name", {
+        retryable: false
+      });
+    }
+    if (!isPrefix(sourcePath, path)) {
+      throw new TBError("unavailable", "remote search source does not own its result", {
+        retryable: false
+      });
+    }
+    const projected = compactItem({ ...item, path, source: { path: sourcePath } });
+    assertHardResultConstraints(projected, constraints);
+    return projected;
+  }).filter((item) => check(ctx, item.path, "read").allow && check(ctx, item.path, "call").allow);
+  const projectedSources = page.sources?.map((source) => ({
+    path: projector.localPath(source.path, true),
+    status: source.status
+  }));
+  const sourceStatuses = /* @__PURE__ */ new Map();
+  for (const source of projectedSources ?? []) {
+    const previous = sourceStatuses.get(source.path);
+    if (previous !== void 0 && previous !== source.status) {
+      throw new TBError("unavailable", "remote search returned conflicting source statuses", {
+        retryable: false
+      });
+    }
+    sourceStatuses.set(source.path, source.status);
+  }
+  const hasFailure = [...sourceStatuses.values()].some((status) => status !== "ok");
+  if (page.partial === true !== hasFailure || page.cursor !== void 0 && !isFederatedSearchSessionHandle(page.cursor) || page.snapshot !== void 0 && !isFederatedSearchSessionHandle(page.snapshot)) {
+    throw new TBError("unavailable", "remote search returned inconsistent page metadata", {
+      retryable: false
+    });
+  }
+  const sources = projectedSources?.filter((source) => check(ctx, source.path, "read").allow && check(ctx, source.path, "call").allow);
+  const visiblePartial = sources?.some((source) => source.status !== "ok") === true;
+  return {
+    items,
+    ...page.cursor === void 0 ? {} : { cursor: page.cursor },
+    ...visiblePartial ? { partial: true } : {},
+    ...sources === void 0 ? {} : { sources }
+  };
+}
+async function remoteResponse(deps, input, node, requestPath, method, headers, deadline, body) {
+  if (node.config?.kind !== "remote") throw invalidContinuation();
+  return await passthroughRemote({
+    actor: {
+      keyId: input.ctx.keyId,
+      owner: input.ctx.owner,
+      traceId: input.ctx.traceId
+    },
+    ...body === void 0 ? {} : { body },
+    config: node.config,
+    headers,
+    maxResponseBodyBytes: federatedSearchSettings(deps.remote).maxResponseBodyBytes,
+    method,
+    nodePath: node.path,
+    requestPath,
+    requestUrl: input.requestUrl,
+    secrets: deps.secrets,
+    settings: await resolveRemoteSettings(input.state, deps.remote),
+    signal: deadlineSignal(deadline)
+  });
+}
+async function assertFederatedCapability(deps, input, node, headers, deadline) {
+  if (node.config?.kind !== "remote" || node.config.skRef === void 0) {
+    throw new TBError("unavailable", "remote search source is unsupported", { retryable: false });
+  }
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${node.path}/~describe`,
+    "GET",
+    headers,
+    deadline
+  );
+  if (!response.ok) {
+    throw new TBError("unavailable", "remote search capability is unavailable", {
+      retryable: response.status >= 500
+    });
+  }
+  const value = await response.json().catch(() => null);
+  if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(value.capabilities) || !value.capabilities.includes("search:federated")) {
+    throw new TBError("unavailable", "remote search source is unsupported", { retryable: false });
+  }
+}
+function childSearchRequest(input, source, cursor) {
+  const opts = input.request.opts ?? {};
+  const childPrefix = childPrefixFor(source.path, opts.pathPrefix).pathPrefix;
+  return {
+    query: input.request.query,
+    opts: {
+      ...opts.effects === void 0 ? {} : { effects: opts.effects },
+      ...cursor === void 0 ? {} : { cursor },
+      detail: "compact",
+      federation: "recursive",
+      limit: 1,
+      matching: opts.matching ?? "best",
+      ...opts.minCoverage === void 0 ? {} : { minCoverage: opts.minCoverage },
+      mode: "keyword",
+      ...childPrefix === void 0 ? {} : { pathPrefix: childPrefix }
+    }
+  };
+}
+async function throwChildSearchError(response) {
+  const error = await response.json().catch(() => null);
+  const message = typeof error?.message === "string" ? error.message : "";
+  if (message.includes("\u73AF")) {
+    throw new TBError("unavailable", "\u68C0\u6D4B\u5230\u900F\u4F20\u73AF", { retryable: false });
+  }
+  if (message.includes("\u8DF3\u6570")) {
+    throw new TBError("unavailable", "\u900F\u4F20\u8DF3\u6570\u8D85\u9650", { retryable: false });
+  }
+  if (response.status >= 400 && response.status < 500) throw invalidContinuation();
+  throw new TBError("unavailable", "remote search unavailable", {
+    retryable: response.status >= 500
+  });
+}
+async function fetchHead(deps, input, source, remoteNodes, deadline, expiresAt, totalTermCount, skipBudget = 20) {
+  if (source.done || source.pending !== void 0) return { statuses: [] };
+  const opts = input.request.opts ?? {};
+  if (source.kind === "local") {
+    const page2 = await executeLocalSearch(
+      {
+        ctx: input.ctx,
+        search: input.search,
+        state: input.state
+      },
+      {
+        query: input.request.query,
+        opts: {
+          ...opts.effects === void 0 ? {} : { effects: opts.effects },
+          ...source.cursor === void 0 ? {} : { cursor: source.cursor },
+          detail: "compact",
+          federation: "local",
+          limit: 1,
+          matching: opts.matching ?? "best",
+          ...opts.minCoverage === void 0 ? {} : { minCoverage: opts.minCoverage },
+          mode: "keyword",
+          ...opts.pathPrefix === void 0 ? {} : { pathPrefix: opts.pathPrefix }
+        }
+      }
+    );
+    const item2 = page2.items[0];
+    if (item2 === void 0) {
+      source.done = page2.cursor === void 0;
+      source.cursor = page2.cursor;
+      return { statuses: [] };
+    }
+    source.pending = compactItem({ ...item2, source: { path: "" } });
+    source.nextCursor = page2.cursor;
+    return { statuses: [] };
+  }
+  const node = remoteNodes.get(source.path);
+  if (node === void 0 || node.config?.kind !== "remote" || !check(input.ctx, node.path, "read").allow || !check(input.ctx, node.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const settings = federatedSearchSettings(deps.remote);
+  const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+  if (remainingMs < settings.minChildWorkMs) {
+    throw new TBError("unavailable", "federated search child has no remaining work budget", {
+      retryable: false
+    });
+  }
+  const headers = federatedHeaders(
+    input.headers,
+    remainingMs,
+    source.budget,
+    expiresAt - Date.now()
+  );
+  const childRequest = childSearchRequest(input, source, source.cursor);
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${node.path}/~search`,
+    "POST",
+    headers,
+    deadline,
+    JSON.stringify(childRequest)
+  );
+  if (!response.ok) await throwChildSearchError(response);
+  const parsed = toolSearchPageSchema.safeParse(await response.json().catch(() => null));
+  if (!parsed.success) {
+    throw new TBError("unavailable", "remote search returned invalid JSON", { retryable: false });
+  }
+  if (parsed.data.items.length > 1) {
+    throw new TBError("unavailable", "remote search exceeded the requested source batch size", {
+      retryable: false
+    });
+  }
+  if (!isFederatedSearchSessionHandle(parsed.data.snapshot)) {
+    throw new TBError("unavailable", "remote search omitted its validation snapshot", {
+      retryable: false
+    });
+  }
+  source.validationCursor = parsed.data.snapshot;
+  const page = projectChildPage(
+    source.path,
+    parsed.data,
+    totalTermCount,
+    input.ctx,
+    input.request
+  );
+  const item = page.items[0];
+  if (item === void 0) {
+    source.done = page.cursor === void 0;
+    source.cursor = page.cursor;
+    if (!source.done) {
+      if (skipBudget <= 1) {
+        throw new TBError("unavailable", "federated search source work budget exhausted", {
+          retryable: false
+        });
+      }
+      return await fetchHead(
+        deps,
+        input,
+        source,
+        remoteNodes,
+        deadline,
+        expiresAt,
+        totalTermCount,
+        skipBudget - 1
+      );
+    }
+  } else {
+    source.pending = item;
+    source.nextCursor = page.cursor;
+  }
+  return { statuses: page.sources?.filter((status) => status.status !== "ok") ?? [] };
+}
+async function validateSourceSnapshots(deps, input, sources, remoteNodes, deadline, expiresAt, maxConcurrency) {
+  const remotes = sources.filter((source) => source.kind === "remote" && source.excluded !== true);
+  await mapLimit(remotes, maxConcurrency, async (source) => {
+    const node = remoteNodes.get(source.path);
+    if (node === void 0 || source.validationCursor === void 0) throw invalidContinuation();
+    const settings = federatedSearchSettings(deps.remote);
+    const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+    if (remainingMs < settings.minChildWorkMs) throw retryableContinuationError();
+    const headers = federatedHeaders(
+      input.headers,
+      remainingMs,
+      source.budget,
+      expiresAt - Date.now()
+    );
+    headers.set(HEADER_VALIDATE_SNAPSHOT, "1");
+    const response = await remoteResponse(
+      deps,
+      input,
+      node,
+      `${node.path}/~search`,
+      "POST",
+      headers,
+      deadline,
+      JSON.stringify(childSearchRequest(input, source, source.validationCursor))
+    );
+    if (!response.ok) await throwChildSearchError(response);
+    const parsed = toolSearchPageSchema.safeParse(await response.json().catch(() => null));
+    if (!parsed.success || parsed.data.items.length !== 0 || parsed.data.cursor !== void 0 || parsed.data.snapshot !== void 0 || parsed.data.partial !== void 0 || parsed.data.sources !== void 0) throw invalidContinuation();
+  });
+}
+function consume(source) {
+  const item = source.pending;
+  if (item === void 0) throw new Error("federated source has no pending item");
+  source.pending = void 0;
+  source.cursor = source.nextCursor;
+  source.nextCursor = void 0;
+  source.done = source.cursor === void 0;
+  return item;
+}
+async function hydrateLocal(input, item) {
+  if (!check(input.ctx, item.path, "read").allow || !check(input.ctx, item.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const registry = new NodeRegistryStore(input.state);
+  const node = await registry.get(item.path).catch(() => null);
+  if (node === null || node.kind !== "mcp" && node.kind !== "http" && node.kind !== "tool" || node.config?.kind !== node.kind) {
+    throw invalidContinuation();
+  }
+  const raw = (await canonicalSearchTools(input.state, [node])).get(node.path);
+  if (raw === void 0) throw invalidContinuation();
+  const matches = virtualizeTools(node.virtualize, raw).exposed.filter((tool2) => tool2.name === item.tool.name);
+  if (matches.length !== 1) throw invalidContinuation();
+  const tool = matches[0];
+  if (tool === void 0) throw invalidContinuation();
+  return { ...item, tool };
+}
+async function hydrateRemote(deps, input, item, source, node, deadline) {
+  if (!check(input.ctx, source.path, "read").allow || !check(input.ctx, source.path, "call").allow || !check(input.ctx, item.path, "read").allow || !check(input.ctx, item.path, "call").allow) {
+    throw invalidContinuation();
+  }
+  const response = await remoteResponse(
+    deps,
+    input,
+    node,
+    `${item.path}/${item.tool.name}/~help`,
+    "GET",
+    (() => {
+      const headers = new Headers({ accept: "application/json" });
+      const via = input.headers.get(HEADER_VIA);
+      if (via !== null) headers.set(HEADER_VIA, via);
+      headers.set(
+        HEADER_REMAINING_MS,
+        String(Math.max(1, Math.floor(deadline - Date.now())))
+      );
+      return headers;
+    })(),
+    deadline
+  );
+  if (!response.ok) {
+    if (response.status >= 400 && response.status < 500) throw invalidContinuation();
+    throw retryableContinuationError();
+  }
+  const parsed = helpJsonSchema.safeParse(await response.json().catch(() => null));
+  if (!parsed.success) throw invalidContinuation();
+  const projected = new RemotePathProjector(source.path).projectHelp(parsed.data, `${item.path}/${item.tool.name}`);
+  const commands = projected.cmds.filter((cmd) => cmd.name === item.tool.name && cmd.path === `/${item.path}/${item.tool.name}` && cmd.scope === "call");
+  if (commands.length !== 1) throw invalidContinuation();
+  const command = commands[0];
+  if (command === void 0) throw invalidContinuation();
+  const tool = {
+    name: command.name,
+    ...command.h === void 0 ? {} : { description: command.h },
+    ...command.effect === void 0 ? {} : { effect: command.effect },
+    ...command.confirm === void 0 ? {} : { confirm: command.confirm },
+    ...command.inputSchema === void 0 ? {} : { inputSchema: command.inputSchema },
+    ...command.outputSchema === void 0 ? {} : { outputSchema: command.outputSchema }
+  };
+  return { ...item, tool };
+}
+async function computePage(deps, input, sources, remoteNodes, deadline, expiresAt, totalTermCount, initial, initialExcluded, maxConcurrency) {
+  let excluded = [...initialExcluded];
+  if (!initial) {
+    await validateSourceSnapshots(
+      deps,
+      input,
+      sources,
+      remoteNodes,
+      deadline,
+      expiresAt,
+      maxConcurrency
+    );
+  }
+  const active = sources.filter((source) => !source.done);
+  const capabilityFailures = await mapLimit(
+    initial ? active.filter((source) => source.kind === "remote") : [],
+    maxConcurrency,
+    async (source) => {
+      const node = remoteNodes.get(source.path);
+      if (node === void 0) return { source, status: "invalid_response" };
+      const settings = federatedSearchSettings(deps.remote);
+      const remainingMs = deadline - Date.now() - settings.perHopReturnReserveMs;
+      if (remainingMs < settings.minChildWorkMs) {
+        return { source, status: "budget_exhausted" };
+      }
+      const headers = federatedHeaders(
+        input.headers,
+        remainingMs,
+        source.budget,
+        expiresAt - Date.now()
+      );
+      try {
+        await assertFederatedCapability(deps, input, node, headers, deadline);
+        return null;
+      } catch (error) {
+        const status = error instanceof TBError && error.message.includes("unsupported") ? "unsupported" : controlledStatus(error);
+        return { error, source, status };
+      }
+    }
+  );
+  for (const failure of capabilityFailures) {
+    if (failure === null) continue;
+    if (!initial) {
+      if (failure.error instanceof TBError && failure.error.code === "invalid_argument") {
+        throw failure.error;
+      }
+      throw failure.status === "unsupported" ? invalidContinuation() : retryableContinuationError();
+    }
+    failure.source.done = true;
+    failure.source.excluded = true;
+    excluded = mergeStatuses(excluded, [{ path: failure.source.path, status: failure.status }]);
+  }
+  const storedPending = sources.filter((source) => source.pending !== void 0);
+  const refreshedStatuses = await mapLimit(storedPending, maxConcurrency, async (source) => {
+    try {
+      const pending = source.pending;
+      if (pending === void 0) throw invalidContinuation();
+      const hydrated = source.kind === "local" ? await hydrateLocal(input, pending) : await (async () => {
+        const node = remoteNodes.get(source.path);
+        if (node === void 0) throw invalidContinuation();
+        return await hydrateRemote(deps, input, pending, source, node, deadline);
+      })();
+      if (!sameJson(compactItem(hydrated), pending)) throw invalidContinuation();
+      return [];
+    } catch (error) {
+      throw continuationSourceError(error);
+    }
+  });
+  excluded = mergeStatuses(excluded, ...refreshedStatuses);
+  let successfulSources = storedPending.length;
+  const headResults = await mapLimit(
+    sources.filter((source) => !source.done && source.pending === void 0),
+    maxConcurrency,
+    async (source) => {
+      try {
+        const result = await fetchHead(
+          deps,
+          input,
+          source,
+          remoteNodes,
+          deadline,
+          expiresAt,
+          totalTermCount
+        );
+        return { ...result, success: true };
+      } catch (error) {
+        if (!initial) throw continuationSourceError(error);
+        source.done = true;
+        source.excluded = true;
+        return {
+          statuses: [{ path: source.path, status: controlledStatus(error) }],
+          success: false
+        };
+      }
+    }
+  );
+  successfulSources += headResults.filter((result) => result.success).length;
+  excluded = mergeStatuses(excluded, ...headResults.map((result) => result.statuses));
+  const items = [];
+  let selectedCoverage;
+  const limit = input.request.opts?.limit ?? 10;
+  while (items.length < limit) {
+    const heads = sources.filter((source2) => source2.pending !== void 0);
+    if (heads.length === 0) break;
+    const highest = Math.max(...heads.map((source2) => source2.pending?.relevance.coverage ?? -1));
+    selectedCoverage ??= highest;
+    if ((input.request.opts?.matching ?? "best") === "best" && highest !== selectedCoverage) break;
+    const bucket = heads.filter((source2) => source2.pending?.relevance.coverage === highest).sort((left, right) => (left.balanceCoverage === highest ? left.balanceCount : 0) - (right.balanceCoverage === highest ? right.balanceCount : 0) || left.path.localeCompare(right.path));
+    const source = bucket[0];
+    if (source === void 0) break;
+    items.push(consume(source));
+    if (source.balanceCoverage !== highest) {
+      source.balanceCoverage = highest;
+      source.balanceCount = 0;
+    }
+    source.balanceCount++;
+    try {
+      const result = await fetchHead(
+        deps,
+        input,
+        source,
+        remoteNodes,
+        deadline,
+        expiresAt,
+        totalTermCount
+      );
+      excluded = mergeStatuses(excluded, result.statuses);
+    } catch (error) {
+      if (!initial) throw continuationSourceError(error);
+      source.done = true;
+      source.excluded = true;
+      excluded = mergeStatuses(excluded, [{ path: source.path, status: controlledStatus(error) }]);
+    }
+  }
+  const partial = excluded.length > 0;
+  const page = {
+    items,
+    ...partial ? { partial: true, sources: excluded } : {}
+  };
+  return { excluded, page, sources, successfulSources };
+}
+function visibleSourceStatuses(ctx, page) {
+  const rawSources = page.sources;
+  const rest = { ...page };
+  delete rest.partial;
+  delete rest.sources;
+  const sources = rawSources?.filter((source) => check(ctx, source.path, "read").allow && check(ctx, source.path, "call").allow);
+  const partial = sources?.some((source) => source.status !== "ok") === true;
+  return {
+    ...rest,
+    ...partial ? { partial: true } : {},
+    ...sources === void 0 || sources.length === 0 ? {} : { sources }
+  };
+}
+async function hydratePage(deps, input, page, sources, remoteNodes, deadline, forceRevalidate = false) {
+  const visiblePage = visibleSourceStatuses(input.ctx, page);
+  const detail = input.request.opts?.detail ?? "compact";
+  if (detail !== "full" && !forceRevalidate) return visiblePage;
+  const constraints = requestConstraints(input.request);
+  const output = [];
+  const encoder = new TextEncoder();
+  let outputBytes = encoder.encode(JSON.stringify({ ...visiblePage, items: [] })).length;
+  const concurrency = federatedSearchSettings(deps.remote).maxConcurrency;
+  for (let offset = 0; offset < visiblePage.items.length; offset += concurrency) {
+    const batch = visiblePage.items.slice(offset, offset + concurrency);
+    const hydrated = await Promise.all(batch.map(async (item) => {
+      const direct = sources.find((source) => source.kind === "remote" && isPrefix(source.path, item.path));
+      const full = direct === void 0 ? await hydrateLocal(input, item) : await (async () => {
+        const node = remoteNodes.get(direct.path);
+        if (node === void 0) throw invalidContinuation();
+        return await hydrateRemote(deps, input, item, direct, node, deadline);
+      })();
+      if (!sameJson(compactItem(full), compactItem(item))) throw invalidContinuation();
+      assertHardResultConstraints(full, constraints);
+      return full;
+    }));
+    if (detail !== "full") continue;
+    for (const item of hydrated) {
+      outputBytes += encoder.encode(JSON.stringify(item)).length;
+      if (outputBytes > TOOL_SEARCH_PAGE_BYTES) {
+        throw new TBError("rate_limited", "federated search page exceeds response byte budget", {
+          retryable: false
+        });
+      }
+      output.push(item);
+    }
+  }
+  return detail === "full" ? { ...visiblePage, items: output } : visiblePage;
+}
+function pageWithCursor(page, cursor) {
+  return cursor === void 0 ? page : { ...page, cursor };
+}
+function assertPageBytes(page) {
+  if (new TextEncoder().encode(JSON.stringify(page)).length > TOOL_SEARCH_PAGE_BYTES) {
+    throw new TBError("rate_limited", "federated search page exceeds response byte budget", {
+      retryable: false
+    });
+  }
+}
+async function executeFederatedSearch(deps, input) {
+  if (deps.remote.instanceId === void 0 || input.state.compareAndSwap === void 0) {
+    throw new TBError(
+      "invalid_argument",
+      "recursive search requires explicit TB_INSTANCE_ID and atomic StateStore CAS"
+    );
+  }
+  if ((input.request.opts?.mode ?? "keyword") !== "keyword") {
+    throw new TBError("invalid_argument", "semantic search cannot use recursive federation");
+  }
+  const wireOpts = input.request.opts ?? {};
+  const constraints = normalizeToolSearchOptions({
+    ...wireOpts.effects === void 0 ? {} : { effects: wireOpts.effects },
+    matching: wireOpts.matching ?? "best",
+    ...wireOpts.minCoverage === void 0 ? {} : { minCoverage: wireOpts.minCoverage },
+    ...wireOpts.pathPrefix === void 0 ? {} : { pathPrefix: wireOpts.pathPrefix }
+  });
+  input = {
+    ...input,
+    request: {
+      query: input.request.query,
+      opts: {
+        ...wireOpts,
+        ...constraints.effects === void 0 ? {} : { effects: constraints.effects },
+        matching: constraints.matching,
+        ...constraints.minCoverage === void 0 ? {} : { minCoverage: constraints.minCoverage },
+        ...constraints.pathPrefix === void 0 ? {} : { pathPrefix: constraints.pathPrefix }
+      }
+    }
+  };
+  const viaError = checkVia(
+    parseVia(input.headers.get(HEADER_VIA) ?? void 0),
+    deps.remote.instanceId,
+    deps.remote.maxHops
+  );
+  if (viaError !== null) throw viaError;
+  const settings = federatedSearchSettings(deps.remote);
+  await input.searchSync?.ensureReady();
+  if (input.search.revision === void 0) {
+    throw new TBError("invalid_argument", "recursive search requires a revisioned search index");
+  }
+  const localRevision = await input.search.revision();
+  const deadlineMs = clampHeader(input.headers.get(HEADER_REMAINING_MS), settings.totalDeadlineMs);
+  const sessionTtlMs = clampHeader(input.headers.get(HEADER_SESSION_TTL_MS), settings.sessionTtlMs);
+  const sourceBudget = clampHeader(input.headers.get(HEADER_SOURCE_BUDGET), settings.maxSources);
+  const deadline = Date.now() + deadlineMs;
+  const expiresAtMs = Date.now() + sessionTtlMs;
+  const limit = input.request.opts?.limit ?? 10;
+  const requestDigest = await sha256Hex(canonicalJson({
+    authorization: input.ctx.scopes,
+    request: requestForDigest(input.request, limit)
+  }));
+  const sessionStore = new FederatedSearchSessionStore(input.state);
+  const plan = prepareToolSearchQuery(input.request.query);
+  const registry = new NodeRegistryStore(input.state);
+  const snapshot = await registry.rootSnapshot(TOOL_SEARCH_AUDIT_NODE_LIMIT);
+  const allDirect = directRemoteNodes(snapshot.items);
+  const eligibleRemotes = allDirect.filter((node) => {
+    const relation = childPrefixFor(node.path, input.request.opts?.pathPrefix);
+    return relation.eligible && check(input.ctx, node.path, "read").allow && check(input.ctx, node.path, "call").allow;
+  });
+  const includeLocal = localEligible(allDirect, input.request.opts?.pathPrefix);
+  const configuredRemotes = eligibleRemotes.filter((node) => node.config?.kind === "remote" && node.config.skRef !== void 0);
+  const secretAvailability = await mapLimit(
+    configuredRemotes,
+    settings.maxConcurrency,
+    async (node) => {
+      if (node.config?.kind !== "remote" || node.config.skRef === void 0) return false;
+      try {
+        return await deps.secrets.resolve(node.config.skRef) !== void 0;
+      } catch {
+        return false;
+      }
+    }
+  );
+  const participatingRemotes = configuredRemotes.filter((_node, index) => secretAvailability[index] === true);
+  const unavailableRemotes = configuredRemotes.filter((_node, index) => secretAvailability[index] !== true);
+  const transportSettings = await resolveRemoteSettings(input.state, deps.remote);
+  const topologyNodes = snapshot.items.filter((node) => check(input.ctx, node.path, "read").allow && check(input.ctx, node.path, "call").allow);
+  const digest = await topologyDigest(topologyNodes, includeLocal, localRevision, {
+    allowInsecure: transportSettings.allowInsecure,
+    allowlist: [...transportSettings.allowlist].sort(),
+    availableRemotes: participatingRemotes.map((node) => node.path),
+    instanceId: transportSettings.instanceId ?? null,
+    maxHops: transportSettings.maxHops
+  });
+  const remoteNodes = new Map(participatingRemotes.map((node) => [node.path, node]));
+  const cursor = input.request.opts?.cursor;
+  if (cursor !== void 0) {
+    const current = await sessionStore.read(cursor, { actorKeyId: input.ctx.keyId, requestDigest });
+    if (current.topologyDigest !== digest || current.rankingVersion !== TOOL_SEARCH_RANKING_VERSION) {
+      throw invalidContinuation();
+    }
+    if (input.headers.get(HEADER_VALIDATE_SNAPSHOT) === "1") {
+      await validateSourceSnapshots(
+        deps,
+        input,
+        current.sourceContinuations,
+        remoteNodes,
+        deadline,
+        Date.parse(current.expiresAt),
+        settings.maxConcurrency
+      );
+      return { items: [] };
+    }
+    if (current.nextHandle === null) throw invalidContinuation();
+    let next;
+    try {
+      next = await sessionStore.read(current.nextHandle, {
+        actorKeyId: input.ctx.keyId,
+        requestDigest
+      });
+    } catch (error) {
+      if (!(error instanceof TBError) || error.code !== "invalid_argument") throw error;
+    }
+    if (next !== void 0) assertNextRecord(current, next, digest);
+    const cachedNext = next !== void 0;
+    if (next === void 0) {
+      const state2 = await computePage(
+        deps,
+        input,
+        structuredClone(current.sourceContinuations),
+        remoteNodes,
+        deadline,
+        Date.parse(current.expiresAt),
+        plan.totalTermCount,
+        false,
+        current.excludedStatuses,
+        settings.maxConcurrency
+      );
+      const hasMore2 = responseHasMore(state2.sources);
+      const nextNextHandle = hasMore2 ? sessionStore.issueHandle() : null;
+      next = await sessionStore.create(current.nextHandle, {
+        actorKeyId: input.ctx.keyId,
+        excludedStatuses: state2.excluded,
+        expiresAt: current.expiresAt,
+        federationPolicy: current.federationPolicy,
+        generation: current.generation + 1,
+        nextHandle: nextNextHandle,
+        page: state2.page,
+        rankingVersion: TOOL_SEARCH_RANKING_VERSION,
+        requestDigest,
+        sessionId: current.sessionId,
+        sourceContinuations: serializableSources(state2.sources),
+        topologyDigest: digest
+      });
+      assertNextRecord(current, next, digest);
+      assertCachedPage(state2, next);
+    }
+    if (cachedNext) {
+      await validateSourceSnapshots(
+        deps,
+        input,
+        next.sourceContinuations,
+        remoteNodes,
+        deadline,
+        Date.parse(next.expiresAt),
+        settings.maxConcurrency
+      );
+    }
+    const wantsSnapshot2 = input.headers.get(HEADER_WANT_SNAPSHOT) === "1";
+    const responsePage2 = {
+      ...pageWithCursor(
+        next.page,
+        next.nextHandle === null ? void 0 : current.nextHandle
+      ),
+      ...wantsSnapshot2 ? { snapshot: current.nextHandle } : {}
+    };
+    const response2 = await hydratePage(
+      deps,
+      input,
+      responsePage2,
+      next.sourceContinuations,
+      remoteNodes,
+      deadline,
+      cachedNext
+    );
+    assertPageBytes(response2);
+    return response2;
+  }
+  const initialExcluded = eligibleRemotes.filter((node) => node.config?.kind === "remote" && node.config.skRef === void 0).map((node) => ({ path: node.path, status: "unsupported" }));
+  initialExcluded.push(...unavailableRemotes.map((node) => ({
+    path: node.path,
+    status: "unavailable"
+  })));
+  const availableRemoteSlots = Math.max(0, sourceBudget - (includeLocal ? 1 : 0));
+  const selectedRemotes = participatingRemotes.slice(0, availableRemoteSlots);
+  for (const node of participatingRemotes.slice(availableRemoteSlots)) {
+    initialExcluded.push({ path: node.path, status: "budget_exhausted" });
+  }
+  if (snapshot.truncated) initialExcluded.push({ path: "", status: "budget_exhausted" });
+  const allocations = selectedRemotes.map((_node, index) => {
+    const base = selectedRemotes.length === 0 ? 0 : Math.floor(availableRemoteSlots / selectedRemotes.length);
+    const extra = index < availableRemoteSlots % Math.max(1, selectedRemotes.length) ? 1 : 0;
+    return Math.max(1, base + extra);
+  });
+  const sources = [
+    ...includeLocal ? [{ balanceCount: 0, budget: 1, done: false, kind: "local", path: "" }] : [],
+    ...selectedRemotes.map((node, index) => ({
+      balanceCount: 0,
+      budget: allocations[index] ?? 1,
+      done: false,
+      kind: "remote",
+      path: node.path
+    }))
+  ];
+  const state = await computePage(
+    deps,
+    input,
+    sources,
+    remoteNodes,
+    deadline,
+    expiresAtMs,
+    plan.totalTermCount,
+    true,
+    initialExcluded,
+    settings.maxConcurrency
+  );
+  const candidateSourceCount = (includeLocal ? 1 : 0) + eligibleRemotes.length;
+  if (candidateSourceCount > 0 && state.successfulSources === 0 && state.page.items.length === 0) {
+    throw new TBError("unavailable", "all federated search sources failed", { retryable: true });
+  }
+  const hasMore = responseHasMore(state.sources);
+  const wantsSnapshot = input.headers.get(HEADER_WANT_SNAPSHOT) === "1";
+  const needsSession = hasMore || wantsSnapshot;
+  const sessionHandle = needsSession ? sessionStore.issueHandle() : void 0;
+  const responseCursor = hasMore ? sessionHandle : void 0;
+  const nextHandle = hasMore ? sessionStore.issueHandle() : null;
+  const responsePage = {
+    ...pageWithCursor(state.page, responseCursor),
+    ...wantsSnapshot && sessionHandle !== void 0 ? { snapshot: sessionHandle } : {}
+  };
+  const response = await hydratePage(
+    deps,
+    input,
+    responsePage,
+    state.sources,
+    remoteNodes,
+    deadline
+  );
+  assertPageBytes(response);
+  if (sessionHandle !== void 0) {
+    await sessionStore.create(sessionHandle, {
+      actorKeyId: input.ctx.keyId,
+      excludedStatuses: state.excluded,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+      federationPolicy: { limit, matching: input.request.opts?.matching ?? "best" },
+      generation: 0,
+      nextHandle,
+      page: state.page,
+      rankingVersion: TOOL_SEARCH_RANKING_VERSION,
+      requestDigest,
+      sourceContinuations: serializableSources(state.sources),
+      topologyDigest: digest
+    });
+  }
+  return response;
+}
+
 // ../app/src/routes/search.ts
+function requestWithNormalizedLimit(request) {
+  return {
+    ...request,
+    opts: {
+      ...request.opts ?? {},
+      limit: normalizeToolSearchLimit(request.opts?.limit)
+    }
+  };
+}
 function registerSearchRoute(app, env) {
   const { deps, globalSearchCapabilities, searchSync } = env;
   app.post(
@@ -37424,8 +39490,7 @@ function registerSearchRoute(app, env) {
       if (body === null || typeof body !== "object" || Array.isArray(body)) {
         throw new TBError("invalid_argument", "body must be a JSON object");
       }
-      const bodyKeys = Object.keys(body);
-      if (bodyKeys.some((key) => key !== "query" && key !== "opts")) {
+      if (Object.keys(body).some((key) => key !== "query" && key !== "opts")) {
         throw new TBError("invalid_argument", "body only accepts query and opts");
       }
       if (typeof body.query !== "string" || body.query.trim().length === 0) {
@@ -37436,102 +39501,72 @@ 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 query = body.query.trim();
-      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 };
-      return new Response(JSON.stringify(result), {
+      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") }
       });
     })
@@ -37719,7 +39754,7 @@ function mcpBridgeFor(c, env, app) {
       invokePath: "/~search",
       mcpName: "tb_search",
       operation: "search",
-      description: "Search visible tools across the Tool Bridge tree.",
+      description: "Search visible tools across the Tool Bridge tree (compact by default).",
       effect: "read",
       inputSchema: {
         type: "object",
@@ -37728,7 +39763,20 @@ function mcpBridgeFor(c, env, app) {
           query: { type: "string", minLength: 1 },
           mode: { type: "string", enum: ["keyword", "semantic"] },
           limit: { type: "integer", minimum: 1, maximum: 200 },
-          cursor: { type: "string", minLength: 1 }
+          cursor: { type: "string", minLength: 1 },
+          detail: { type: "string", enum: ["compact", "full"], default: "compact" },
+          effects: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "string",
+              enum: ["read", "write", "destructive", "unknown"]
+            }
+          },
+          federation: { type: "string", enum: ["local", "recursive"] },
+          matching: { type: "string", enum: ["best", "all"] },
+          minCoverage: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+          pathPrefix: { type: "string", minLength: 1 }
         },
         required: ["query"]
       }
@@ -37936,15 +39984,27 @@ function mcpBridgeFor(c, env, app) {
         if (tool.operation === "search") {
           headers2.set("accept", "application/json");
           headers2.set("content-type", "application/json");
-          const opts = Object.fromEntries(
-            ["mode", "limit", "cursor"].filter((key) => args[key] !== void 0).map((key) => [key, args[key]])
-          );
+          const opts = {
+            detail: args.detail ?? "compact",
+            ...Object.fromEntries(
+              [
+                "mode",
+                "limit",
+                "cursor",
+                "effects",
+                "federation",
+                "matching",
+                "minCoverage",
+                "pathPrefix"
+              ].filter((key) => args[key] !== void 0).map((key) => [key, args[key]])
+            )
+          };
           const response2 = await app.request(new Request(new URL("/~search", c.req.url), {
             method: "POST",
             headers: headers2,
             body: JSON.stringify({
               query: args.query,
-              ...Object.keys(opts).length === 0 ? {} : { opts }
+              opts
             })
           }));
           return await resultFromResponse(response2);
@@ -38102,27 +40162,27 @@ async function handleInvoke(c, env) {
       throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${command}'`);
     }
     if (directUpload) {
-      const result3 = await createContextUploadGrant(
-        node,
-        cfg,
-        deps,
-        args2
+      const result3 = await dispatchContextUploadCmd(
+        args2,
+        (input) => createContextUploadGrant(node, cfg, deps, input)
       );
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
     if (cfg.provider === "device-fs") {
+      const forwardedArgs = parseContextCmdArgs(command, args2);
       const result3 = await invokeDevice(deps, deviceIdForDeviceFs(cfg), {
         path: `fs/${command}`,
-        arguments: args2,
+        arguments: forwardedArgs,
         context: deviceCallContextFrom(ctx)
       });
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
     const contextMarker = deviceMarkerOf(cfg.providerConfig);
     if (cfg.provider !== "r2" && cfg.provider !== "s3" && contextMarker !== null) {
+      const forwardedArgs = parseContextCmdArgs(command, args2);
       const result3 = await invokeDevice(deps, contextMarker.deviceId, {
         path: `${relativeDevicePath(node.path, contextMarker.mountPath)}/${command}`,
-        arguments: args2,
+        arguments: forwardedArgs,
         context: deviceCallContextFrom(ctx)
       });
       return renderResult(result3, negotiate(c.req.header("accept")));
@@ -38130,7 +40190,7 @@ async function handleInvoke(c, env) {
     if (cfg.provider !== "r2" && cfg.provider !== "s3") {
       const local = localContext(deps, node);
       if (local !== null) {
-        const result4 = await dispatchContextCmd(local, command, args2);
+        const result4 = await dispatchContextCmd2(local, command, args2);
         return renderResult(result4, negotiate(c.req.header("accept")));
       }
       const { manifest, export: exported } = await requirePluginExport(
@@ -38150,11 +40210,11 @@ async function handleInvoke(c, env) {
         ...cfg.authRef !== void 0 ? { upstreamAuthRef: cfg.authRef } : {},
         ...deps.pluginBindings !== void 0 ? { bindings: deps.pluginBindings } : {}
       });
-      const result3 = await dispatchContextCmd(provider2, command, args2);
+      const result3 = await dispatchContextCmd2(provider2, command, args2);
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
     const provider = await contextProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchContextCmd(provider, command, args2);
+    const result2 = await dispatchContextCmd2(provider, command, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind === "skillhub" && node.config?.kind === "skillhub") {
@@ -38172,7 +40232,7 @@ async function handleInvoke(c, env) {
       throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${command}'`);
     }
     const provider = await skillhubProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchSkillhubCmd(provider, command, args2);
+    const result2 = await dispatchSkillhubCmd2(provider, command, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind !== "builtin" || node.config?.kind !== "builtin") {
@@ -38205,6 +40265,7 @@ async function handleInvoke(c, env) {
       deps
     );
     assertSecretRefUse(ctx.scopes, cfgPatch);
+    await assertMcpOAuthConfig(cfgPatch, deps.secrets);
     await assertContextConfig(cfgPatch, deps);
     await assertSkillhubConfig(cfgPatch, deps);
     await assertToolConfig(cfgPatch, deps, ctx, targetPath);
@@ -38228,7 +40289,7 @@ async function handleInvoke(c, env) {
   let result;
   try {
     result = await mod.dispatch(cmd, args, ctx, {
-      requestOrigin: deps.canonicalOrigin ?? new URL(c.req.url).origin
+      requestOrigin: resolveStoreRequestOrigin(c.req.url, deps.canonicalOrigin)
     });
   } catch (error) {
     await searchSync?.abort(registryMarker);
@@ -38300,6 +40361,7 @@ function createRouteEnv(deps) {
     if (!declared.has("search")) return [];
     return [
       "search",
+      ...deps.remote.instanceId !== void 0 && deps.state.compareAndSwap !== void 0 && deps.search?.revision !== void 0 ? ["search:federated"] : [],
       ...declared.has("search:semantic") ? ["search:semantic"] : []
     ];
   };
@@ -38336,11 +40398,20 @@ 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 schemas = c.req.query("schemas") === "1";
+  const schemas2 = c.req.query("schemas") === "1";
   let node;
   try {
     node = await registry.get(path);
@@ -38349,14 +40420,14 @@ async function handleHelp(c, env) {
     if (toolModel !== null) return renderHelp(await enrichHelp(toolModel, path, store), rep);
     const cmdModel = await commandHelpModelFor(registry, ctx, builtins, deps, path, {
       refresh,
-      schemas
+      schemas: schemas2
     });
     if (cmdModel !== null) return renderHelp(await enrichHelp(cmdModel, path, store), rep);
     throw TBError.notFound("not found");
   }
   const model = await helpModelFor(node, registry, ctx, builtins, deps, {
     refresh,
-    schemas,
+    schemas: schemas2,
     now: (/* @__PURE__ */ new Date()).toISOString()
   });
   return renderHelp(await enrichHelp(model, path, store), rep);
@@ -38364,18 +40435,45 @@ async function handleHelp(c, env) {
 
 // ../app/src/routes/tree.ts
 var REMOTE_OPAQUE_KINDS = /* @__PURE__ */ new Set(["remote"]);
+function renderTree(tree, rep) {
+  if (rep === "json") {
+    return new Response(JSON.stringify(treeJsonSchema.parse(tree)), {
+      headers: { "content-type": contentTypeFor("json") }
+    });
+  }
+  if (rep === "dsl") {
+    return new Response(renderTreeDsl(tree), {
+      headers: { "content-type": contentTypeFor("dsl") }
+    });
+  }
+  return new Response(`\`\`\`text
+${renderTreeDsl(tree)}\`\`\`
+`, {
+    headers: { "content-type": contentTypeFor("markdown") }
+  });
+}
 async function handleTree(c, env) {
   const { deps } = env;
   const path = splitReserved(new URL(c.req.url).pathname, "~tree");
   if (path === null) throw TBError.notFound("no such path");
   const ctx = c.get("ctx");
   const store = c.get("store");
+  const rep = negotiate(c.req.header("accept"));
   if (path !== "" && !check(ctx, path, "read").allow) throw TBError.notFound("not found");
   const registry = new NodeRegistryStore(store);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   if (path !== "") {
-    const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~tree", deps);
-    if (remote) return remote;
+    const projector = await remotePathProjectorIfMatch(registry, path);
+    if (projector !== null) {
+      const headers = new Headers(c.req.raw.headers);
+      headers.set("accept", "application/json");
+      const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~tree", deps, headers);
+      if (remote === null) throw remoteProtocolError("remote ~tree lost its mount owner");
+      if (!remote.ok) return remote;
+      const parsed = treeJsonSchema.safeParse(await remote.json().catch(() => null));
+      if (!parsed.success) throw remoteProtocolError("remote ~tree returned invalid JSON");
+      return renderTree(projector.projectTree(parsed.data, path, ctx), rep);
+    }
   }
   let rootEntry;
   if (path !== "") {
@@ -38406,22 +40504,7 @@ async function handleTree(c, env) {
     opaqueKinds: REMOTE_OPAQUE_KINDS,
     ...rootEntry !== void 0 ? { rootEntry } : {}
   });
-  const rep = negotiate(c.req.header("accept"));
-  if (rep === "json") {
-    return new Response(JSON.stringify(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
@@ -39224,6 +41307,40 @@ var FsObjectStore = class {
 // ../core/src/node/shellExecutor.ts
 import { spawn as nodeSpawn } from "child_process";
 var SHELL_OUTPUT_LIMIT_BYTES = 1024 * 1024;
+var SHELL_EXEC_DEFAULT_TIMEOUT_MS = 55e3;
+
+// ../core/src/node/structuredCommand.ts
+import { spawn as nodeSpawn2 } from "child_process";
+var STRUCTURED_COMMAND_PROFILE_VERSION = 1;
+var STRUCTURED_COMMAND_MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+var envNameSchema = external_exports.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+var argumentSchema = external_exports.strictObject({
+  input: external_exports.string().min(1),
+  description: external_exports.string().min(1).optional(),
+  flag: external_exports.string().min(1).optional(),
+  choices: external_exports.array(external_exports.string()).min(1).optional(),
+  multiple: external_exports.boolean().optional(),
+  required: external_exports.boolean().optional(),
+  type: external_exports.enum(["string", "number", "boolean"]).optional()
+});
+var commandSchema = external_exports.strictObject({
+  name: external_exports.string().min(1),
+  description: external_exports.string().min(1),
+  executable: external_exports.string().min(1),
+  argv: external_exports.array(external_exports.union([external_exports.string(), argumentSchema])).optional(),
+  cwd: external_exports.string().min(1).optional(),
+  effect: external_exports.enum(["read", "write", "destructive"]),
+  confirm: external_exports.boolean().optional(),
+  timeoutMs: external_exports.number().int().positive().max(SHELL_EXEC_DEFAULT_TIMEOUT_MS).optional(),
+  maxOutputBytes: external_exports.number().int().positive().max(STRUCTURED_COMMAND_MAX_OUTPUT_BYTES).optional(),
+  inheritEnv: external_exports.array(envNameSchema).optional()
+});
+var profileSchema = external_exports.strictObject({
+  version: external_exports.literal(STRUCTURED_COMMAND_PROFILE_VERSION),
+  path: external_exports.string().min(1),
+  description: external_exports.string().min(1),
+  commands: external_exports.array(commandSchema).min(1)
+});
 
 // src/objects.ts
 import { dirname as dirname2, join as join2, sep as sep2 } from "path";
@@ -39507,7 +41624,7 @@ var PgSearchDriver = class {
       records,
       PG_SEARCH_TOOLS_TABLE,
       PG_SEARCH_TOOLS_COLUMNS,
-      (record2) => [record2.path, record2.name, record2.description, record2.feedback]
+      (record2) => [record2.path, record2.name, record2.description, record2.effect, record2.feedback]
     );
   }
   insertSnapshots(digests) {
@@ -39697,7 +41814,7 @@ var SqliteSearchDriver = class {
   }
   insertRecords(records) {
     return records.map((record2) => ({
-      params: [record2.path, record2.name, record2.description, record2.feedback],
+      params: [record2.path, record2.name, record2.description, record2.effect, record2.feedback],
       sql: TOOL_SEARCH_INSERT_SQL
     }));
   }
@@ -39841,7 +41958,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.16.0",
+  version: "0.19.0",
   description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite or PostgreSQL persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
   type: "module",
   license: "MIT",
@@ -40023,6 +42140,7 @@ function resolveUiAssets(uiDirOverride) {
 }
 
 // src/server.ts
+var providerOAuthFetch = createGuardedFetch({ crossOriginRedirect: "error" });
 function pgBackends(databaseUrl) {
   const sql = postgres(databaseUrl, { onnotice: () => {
   } });
@@ -40136,6 +42254,7 @@ function createTbServer(config) {
   const deps = {
     state,
     secrets,
+    providerOAuthFetch,
     version: package_default.version,
     remote: config.remote,
     search,