@tool-bridge/server 0.17.0 → 0.20.0

package/dist/{chunk-RVWZN3CI.js → chunk-WIGQCP6O.js}

@@ -1328,16 +1328,16 @@ function cleanEnum(obj) {
 }
 function base64ToUint8Array(base644) {
   const binaryString = atob(base644);
-  const bytes = new Uint8Array(binaryString.length);
+  const bytes2 = new Uint8Array(binaryString.length);
   for (let i = 0; i < binaryString.length; i++) {
-    bytes[i] = binaryString.charCodeAt(i);
+    bytes2[i] = binaryString.charCodeAt(i);
   }
-  return bytes;
+  return bytes2;
 }
-function uint8ArrayToBase64(bytes) {
+function uint8ArrayToBase64(bytes2) {
   let binaryString = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binaryString += String.fromCharCode(bytes[i]);
+  for (let i = 0; i < bytes2.length; i++) {
+    binaryString += String.fromCharCode(bytes2[i]);
   }
   return btoa(binaryString);
 }
@@ -1346,22 +1346,22 @@ function base64urlToUint8Array(base64url3) {
   const padding = "=".repeat((4 - base644.length % 4) % 4);
   return base64ToUint8Array(base644 + padding);
 }
-function uint8ArrayToBase64url(bytes) {
-  return uint8ArrayToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+function uint8ArrayToBase64url(bytes2) {
+  return uint8ArrayToBase64(bytes2).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 function hexToUint8Array(hex3) {
   const cleanHex = hex3.replace(/^0x/, "");
   if (cleanHex.length % 2 !== 0) {
     throw new Error("Invalid hex string length");
   }
-  const bytes = new Uint8Array(cleanHex.length / 2);
+  const bytes2 = new Uint8Array(cleanHex.length / 2);
   for (let i = 0; i < cleanHex.length; i += 2) {
-    bytes[i / 2] = Number.parseInt(cleanHex.slice(i, i + 2), 16);
+    bytes2[i / 2] = Number.parseInt(cleanHex.slice(i, i + 2), 16);
   }
-  return bytes;
+  return bytes2;
 }
-function uint8ArrayToHex(bytes) {
-  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+function uint8ArrayToHex(bytes2) {
+  return Array.from(bytes2).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 var Class = class {
   constructor(..._args) {
@@ -14873,6 +14873,10 @@ function secretRefsInConfig(config2) {
   const refs = [];
   const oauthMcp = c.kind === "mcp" && c.auth === "oauth";
   if (!oauthMcp && typeof c.authRef === "string" && c.authRef.length > 0) refs.push(c.authRef);
+  if (oauthMcp && c.oauthClient !== null && typeof c.oauthClient === "object") {
+    const secretRef = c.oauthClient.clientSecretRef;
+    if (typeof secretRef === "string" && secretRef.length > 0) refs.push(secretRef);
+  }
   if (typeof c.skRef === "string" && c.skRef.length > 0) refs.push(c.skRef);
   return refs;
 }
@@ -14889,17 +14893,17 @@ function assertSecretRefUse(scopes, config2) {
 
 // ../core/src/encoding/base64url.ts
 var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-function base64urlEncode(bytes) {
+function base64urlEncode(bytes2) {
   let out = "";
-  for (let i = 0; i < bytes.length; i += 3) {
-    const a = bytes[i] ?? 0;
-    const b = bytes[i + 1] ?? 0;
-    const c = bytes[i + 2] ?? 0;
+  for (let i = 0; i < bytes2.length; i += 3) {
+    const a = bytes2[i] ?? 0;
+    const b = bytes2[i + 1] ?? 0;
+    const c = bytes2[i + 2] ?? 0;
     const n = a << 16 | b << 8 | c;
     out += ALPHABET[n >>> 18 & 63];
     out += ALPHABET[n >>> 12 & 63];
-    if (i + 1 < bytes.length) out += ALPHABET[n >>> 6 & 63];
-    if (i + 2 < bytes.length) out += ALPHABET[n & 63];
+    if (i + 1 < bytes2.length) out += ALPHABET[n >>> 6 & 63];
+    if (i + 2 < bytes2.length) out += ALPHABET[n & 63];
   }
   return out;
 }
@@ -14907,7 +14911,7 @@ function base64urlDecode(input) {
   if (input.length % 4 === 1 || !/^[A-Za-z0-9_-]*$/.test(input)) {
     throw new Error("base64urlDecode: malformed base64url input");
   }
-  const bytes = [];
+  const bytes2 = [];
   for (let i = 0; i < input.length; i += 4) {
     const chunk = input.slice(i, i + 4);
     const a = ALPHABET.indexOf(chunk[0] ?? "");
@@ -14915,11 +14919,11 @@ function base64urlDecode(input) {
     const c = chunk.length >= 3 ? ALPHABET.indexOf(chunk[2] ?? "") : 0;
     const d = chunk.length >= 4 ? ALPHABET.indexOf(chunk[3] ?? "") : 0;
     const n = a << 18 | b << 12 | c << 6 | d;
-    bytes.push(n >>> 16 & 255);
-    if (chunk.length >= 3) bytes.push(n >>> 8 & 255);
-    if (chunk.length >= 4) bytes.push(n & 255);
+    bytes2.push(n >>> 16 & 255);
+    if (chunk.length >= 3) bytes2.push(n >>> 8 & 255);
+    if (chunk.length >= 4) bytes2.push(n & 255);
   }
-  return new Uint8Array(bytes);
+  return new Uint8Array(bytes2);
 }
 
 // ../core/src/omit.ts
@@ -14938,8 +14942,8 @@ async function sha256Hex(text) {
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
 }
 function generateSecret() {
-  const bytes = crypto.getRandomValues(new Uint8Array(16));
-  return `${SECRET_PREFIX}${base64urlEncode(bytes)}`;
+  const bytes2 = crypto.getRandomValues(new Uint8Array(16));
+  return `${SECRET_PREFIX}${base64urlEncode(bytes2)}`;
 }
 function normalizeExpiresAt(value) {
   const parsed = ISO_TIMESTAMP.safeParse(value);
@@ -14996,10 +15000,10 @@ function clampLimit(limit) {
   return Math.min(Math.max(1, limit), LIST_LIMIT_MAX);
 }
 var SKRegistryStore = class {
+  store;
   constructor(store) {
     this.store = store;
   }
-  store;
   async recordById(id) {
     const hash2 = await this.store.get(KEY_SK_ID + id);
     if (typeof hash2 !== "string") return null;
@@ -15111,6 +15115,7 @@ var OperationRegistry = class {
     const schema = spec.inputSchema !== void 0 ? normalizeSchema(spec.inputSchema) : void 0;
     const toolSpec = { name };
     if (spec.description !== void 0) toolSpec.description = spec.description;
+    if (spec.delivery !== void 0) toolSpec.delivery = spec.delivery;
     if (spec.effect !== void 0) toolSpec.effect = spec.effect;
     if (spec.confirm !== void 0) toolSpec.confirm = spec.confirm;
     if (schema !== void 0) toolSpec.inputSchema = toJsonSchema(schema);
@@ -15589,7 +15594,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       opts: HTBP_LIST_OPTIONS_SCHEMA.optional()
     }),
     returns: "Page<ContextEntryMeta>",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ opts, path }, { provider }) => provider.list(path ?? "", opts)
 ).register(
@@ -15600,7 +15606,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       path: external_exports.string().describe("entry path inside the namespace")
     }),
     returns: "ContextEntry",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ path }, { provider }) => provider.get(path)
 ).register(
@@ -15612,7 +15619,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       entry: entrySchema
     }),
     returns: "ContextEntryMeta",
-    scope: "write"
+    scope: "write",
+    effect: "write"
   },
   ({ entry, path }, { provider }) => provider.write(path, entry)
 ).register(
@@ -15624,7 +15632,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       patch: patchSchema
     }),
     returns: "ContextEntryMeta",
-    scope: "write"
+    scope: "write",
+    effect: "write"
   },
   ({ patch, path }, { provider }) => provider.update(path, patch)
 ).register(
@@ -15647,7 +15656,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       opts: searchOptionsSchema.optional()
     }),
     returns: "Page<ContextEntryMeta>",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ opts, query }, { provider }) => provider.search(query, opts)
 ).register(
@@ -16608,6 +16618,661 @@ function createFederationModule(deps) {
   return COMMANDS5.module(deps);
 }
 
+// ../core/src/device/mailbox.ts
+var KEY_DEVICE_OPERATION = "deviceop:";
+var DEVICE_OPERATION_STATES = [
+  "queued",
+  "claimed",
+  "succeeded",
+  "rejected",
+  "failed",
+  "result_unknown",
+  "cancelled",
+  "expired"
+];
+var DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+var MAX_TTL_SECONDS = 7 * 24 * 60 * 60;
+var DEFAULT_LEASE_SECONDS = 60;
+var DEFAULT_MAX_PAYLOAD_BYTES = 256 * 1024;
+var DEFAULT_MAX_PENDING_PER_DEVICE = 1e3;
+var DEFAULT_TERMINAL_RETENTION_SECONDS = 7 * 24 * 60 * 60;
+var MAX_CAS_ATTEMPTS = 8;
+var LIST_LIMIT_DEFAULT2 = 50;
+var LIST_LIMIT_MAX2 = 200;
+var HKDF_SALT = new TextEncoder().encode("tool-bridge:device-mailbox:v1");
+var HKDF_INFO = new TextEncoder().encode("aes-256-gcm:operation-payload-and-result:v1");
+function mailboxUnavailable(message) {
+  return new TBError("unavailable", message, { retryable: false });
+}
+function finiteTimestamp(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value !== "";
+}
+function positiveInteger(value, fallback, field) {
+  const actual = value ?? fallback;
+  if (!Number.isSafeInteger(actual) || actual < 1) {
+    throw new TBError("invalid_argument", `${field} must be a positive integer`);
+  }
+  return actual;
+}
+function clampLimit3(value) {
+  if (value === void 0) return LIST_LIMIT_DEFAULT2;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new TBError("invalid_argument", "limit must be a positive integer");
+  }
+  return Math.min(value, LIST_LIMIT_MAX2);
+}
+function isState(value) {
+  return typeof value === "string" && DEVICE_OPERATION_STATES.includes(value);
+}
+function isTerminal(state) {
+  return state !== "queued" && state !== "claimed";
+}
+function parseEncrypted(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("invalid encrypted value");
+  const raw = value;
+  if (raw.v !== 1 || !nonEmpty(raw.iv) || !nonEmpty(raw.ciphertext)) {
+    throw new Error("invalid encrypted value");
+  }
+  return { v: 1, iv: raw.iv, ciphertext: raw.ciphertext };
+}
+function parseRecord(value) {
+  try {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error();
+    const raw = value;
+    if (raw.v !== 1 || !Number.isSafeInteger(raw.revision) || raw.revision < 1 || !nonEmpty(raw.operationId) || raw.commandId !== raw.operationId || !nonEmpty(raw.deviceId) || !nonEmpty(raw.deviceKeyId) || !nonEmpty(raw.mountPath) || !nonEmpty(raw.targetPath) || !nonEmpty(raw.path) || !nonEmpty(raw.callerKeyId) || !nonEmpty(raw.callerOwner) || !nonEmpty(raw.traceId) || !finiteTimestamp(raw.createdAt) || !finiteTimestamp(raw.updatedAt) || !finiteTimestamp(raw.expiresAt) || !isState(raw.state) || !Number.isSafeInteger(raw.attempt) || raw.attempt < 0 || typeof raw.executionMayHaveOccurred !== "boolean") throw new Error();
+    if (raw.leaseId === void 0 !== (raw.leaseUntil === void 0)) throw new Error();
+    if (raw.leaseId !== void 0 && (!nonEmpty(raw.leaseId) || !finiteTimestamp(raw.leaseUntil))) {
+      throw new Error();
+    }
+    if (raw.cancelRequestedAt !== void 0 && !finiteTimestamp(raw.cancelRequestedAt)) throw new Error();
+    if (raw.terminalAt !== void 0 && !finiteTimestamp(raw.terminalAt)) throw new Error();
+    if (isTerminal(raw.state) && raw.terminalAt === void 0) throw new Error();
+    return {
+      v: 1,
+      revision: raw.revision,
+      operationId: raw.operationId,
+      commandId: raw.commandId,
+      deviceId: raw.deviceId,
+      deviceKeyId: raw.deviceKeyId,
+      mountPath: raw.mountPath,
+      targetPath: raw.targetPath,
+      path: raw.path,
+      callerKeyId: raw.callerKeyId,
+      callerOwner: raw.callerOwner,
+      traceId: raw.traceId,
+      createdAt: raw.createdAt,
+      updatedAt: raw.updatedAt,
+      expiresAt: raw.expiresAt,
+      state: raw.state,
+      attempt: raw.attempt,
+      executionMayHaveOccurred: raw.executionMayHaveOccurred,
+      payload: parseEncrypted(raw.payload),
+      ...raw.leaseId === void 0 ? {} : { leaseId: raw.leaseId, leaseUntil: raw.leaseUntil },
+      ...raw.cancelRequestedAt === void 0 ? {} : { cancelRequestedAt: raw.cancelRequestedAt },
+      ...raw.completedLeaseId === void 0 ? {} : { completedLeaseId: String(raw.completedLeaseId) },
+      ...raw.terminalAt === void 0 ? {} : { terminalAt: raw.terminalAt },
+      ...raw.terminalData === void 0 ? {} : { terminalData: parseEncrypted(raw.terminalData) },
+      ...raw.idempotencyFingerprint === void 0 ? {} : { idempotencyFingerprint: String(raw.idempotencyFingerprint) }
+    };
+  } catch {
+    throw new TBError("internal", "device mailbox record is invalid", { retryable: false });
+  }
+}
+function canonicalJson(value) {
+  if (value === null) return "null";
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TBError("invalid_argument", "mailbox data must be valid JSON");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value !== "object") {
+    throw new TBError("invalid_argument", "mailbox data must be valid JSON");
+  }
+  const object2 = value;
+  const keys = Object.keys(object2).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(object2[key])}`).join(",")}}`;
+}
+function safeError(value) {
+  if (typeof value !== "object" || value === null || typeof value.code !== "string" || typeof value.message !== "string" || typeof value.retryable !== "boolean") throw new TBError("invalid_argument", "completion error is invalid");
+  return { code: value.code, message: value.message, retryable: value.retryable };
+}
+function normalizeCompletion(value) {
+  if (value.outcome === "succeeded") {
+    canonicalJson(value.result);
+    return { outcome: "succeeded", result: value.result };
+  }
+  if (value.outcome === "rejected" || value.outcome === "failed") {
+    return { outcome: value.outcome, error: safeError(value.error) };
+  }
+  return {
+    outcome: "result_unknown",
+    ...value.error === void 0 ? {} : { error: safeError(value.error) }
+  };
+}
+function bytes(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function randomId(randomBytes) {
+  const value = randomBytes(18);
+  if (!(value instanceof Uint8Array) || value.length !== 18) {
+    throw mailboxUnavailable("device mailbox randomness is unavailable");
+  }
+  return `dop_${base64urlEncode(value)}`;
+}
+async function digestBytes(value) {
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)));
+}
+async function deterministicOperationId(binding) {
+  return `dop_${base64urlEncode((await digestBytes(binding)).slice(0, 18))}`;
+}
+async function devicePrefix(deviceId) {
+  return `${KEY_DEVICE_OPERATION}${await sha256Hex(deviceId)}:`;
+}
+async function stateKey(deviceId, operationId) {
+  if (!/^dop_[A-Za-z0-9_-]{24}$/.test(operationId)) {
+    throw new TBError("invalid_argument", "operationId is invalid");
+  }
+  return await devicePrefix(deviceId) + operationId;
+}
+var DeviceMailboxCipher = class {
+  root;
+  keyPromise;
+  constructor(masterKey) {
+    let decoded;
+    try {
+      decoded = base64urlDecode(masterKey);
+    } catch {
+      throw mailboxUnavailable("device mailbox encryption key is invalid");
+    }
+    if (decoded.length !== 32) {
+      throw mailboxUnavailable("device mailbox encryption key is invalid");
+    }
+    this.root = decoded;
+  }
+  key() {
+    this.keyPromise ??= (async () => {
+      const rootKey = await crypto.subtle.importKey("raw", this.root, "HKDF", false, ["deriveKey"]);
+      return await crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: HKDF_SALT, info: HKDF_INFO },
+        rootKey,
+        { name: "AES-GCM", length: 256 },
+        false,
+        ["encrypt", "decrypt"]
+      );
+    })();
+    return this.keyPromise;
+  }
+  async encrypt(operationId, field, value) {
+    const plaintext = canonicalJson(value);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const additionalData = new TextEncoder().encode(`tool-bridge:device-mailbox:v1:${operationId}:${field}`);
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv, additionalData },
+      await this.key(),
+      new TextEncoder().encode(plaintext)
+    );
+    return {
+      v: 1,
+      iv: base64urlEncode(iv),
+      ciphertext: base64urlEncode(new Uint8Array(ciphertext))
+    };
+  }
+  async decrypt(operationId, field, value) {
+    try {
+      const iv = base64urlDecode(value.iv);
+      const ciphertext = base64urlDecode(value.ciphertext);
+      if (iv.length !== 12) throw new Error("invalid iv");
+      const additionalData = new TextEncoder().encode(`tool-bridge:device-mailbox:v1:${operationId}:${field}`);
+      const plaintext = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv, additionalData },
+        await this.key(),
+        ciphertext
+      );
+      return JSON.parse(new TextDecoder().decode(plaintext));
+    } catch {
+      throw new TBError("internal", "device mailbox data cannot be decrypted", { retryable: false });
+    }
+  }
+};
+var DeviceMailboxService = class {
+  cas;
+  cipher;
+  defaultTtlSeconds;
+  leaseSeconds;
+  maxPayloadBytes;
+  maxPendingPerDevice;
+  maxTtlSeconds;
+  now;
+  randomBytes;
+  state;
+  terminalRetentionSeconds;
+  constructor(state, encryptionRoot, opts = {}) {
+    if (state.compareAndSwap === void 0) {
+      throw mailboxUnavailable("device mailbox requires StateStore.compareAndSwap");
+    }
+    if (encryptionRoot === void 0) {
+      throw mailboxUnavailable("device mailbox requires TB_SECRET_ENCRYPTION_KEY");
+    }
+    this.cas = state.compareAndSwap.bind(state);
+    this.state = state;
+    this.cipher = new DeviceMailboxCipher(encryptionRoot);
+    this.defaultTtlSeconds = positiveInteger(
+      opts.defaultTtlSeconds,
+      DEFAULT_TTL_SECONDS,
+      "defaultTtlSeconds"
+    );
+    this.maxTtlSeconds = positiveInteger(opts.maxTtlSeconds, MAX_TTL_SECONDS, "maxTtlSeconds");
+    if (this.defaultTtlSeconds > this.maxTtlSeconds) {
+      throw new TBError("invalid_argument", "defaultTtlSeconds cannot exceed maxTtlSeconds");
+    }
+    this.leaseSeconds = positiveInteger(opts.leaseSeconds, DEFAULT_LEASE_SECONDS, "leaseSeconds");
+    this.maxPayloadBytes = positiveInteger(
+      opts.maxPayloadBytes,
+      DEFAULT_MAX_PAYLOAD_BYTES,
+      "maxPayloadBytes"
+    );
+    this.maxPendingPerDevice = positiveInteger(
+      opts.maxPendingPerDevice,
+      DEFAULT_MAX_PENDING_PER_DEVICE,
+      "maxPendingPerDevice"
+    );
+    this.terminalRetentionSeconds = positiveInteger(
+      opts.terminalRetentionSeconds,
+      DEFAULT_TERMINAL_RETENTION_SECONDS,
+      "terminalRetentionSeconds"
+    );
+    this.now = opts.now ?? (() => Date.now());
+    this.randomBytes = opts.randomBytes ?? ((length) => crypto.getRandomValues(new Uint8Array(length)));
+  }
+  nowIso() {
+    return new Date(this.now()).toISOString();
+  }
+  async read(deviceId, operationId) {
+    const key = await stateKey(deviceId, operationId);
+    const value = await this.state.get(key);
+    if (value === null) throw TBError.notFound("device operation not found");
+    const record2 = parseRecord(value);
+    if (record2.deviceId !== deviceId || record2.operationId !== operationId) {
+      throw new TBError("internal", "device mailbox record identity mismatch", { retryable: false });
+    }
+    return { key, record: record2 };
+  }
+  summary(record2) {
+    return {
+      operationId: record2.operationId,
+      commandId: record2.commandId,
+      deviceId: record2.deviceId,
+      mountPath: record2.mountPath,
+      targetPath: record2.targetPath,
+      caller: { keyId: record2.callerKeyId, owner: record2.callerOwner },
+      traceId: record2.traceId,
+      createdAt: record2.createdAt,
+      updatedAt: record2.updatedAt,
+      expiresAt: record2.expiresAt,
+      state: record2.state,
+      attempt: record2.attempt,
+      executionMayHaveOccurred: record2.executionMayHaveOccurred,
+      ...record2.leaseUntil === void 0 ? {} : { leaseUntil: record2.leaseUntil },
+      ...record2.cancelRequestedAt === void 0 ? {} : { cancelRequestedAt: record2.cancelRequestedAt },
+      ...record2.terminalAt === void 0 ? {} : { terminalAt: record2.terminalAt }
+    };
+  }
+  async detail(record2) {
+    const summary = this.summary(record2);
+    if (record2.terminalData === void 0) return summary;
+    const terminal = await this.cipher.decrypt(
+      record2.operationId,
+      "terminal",
+      record2.terminalData
+    );
+    if (record2.state === "succeeded") return { ...summary, result: terminal.result };
+    const error51 = terminal.error;
+    if (error51 === void 0) return summary;
+    return { ...summary, error: safeError(error51) };
+  }
+  async expireRecord(key, record2) {
+    let current = record2;
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+      if (isTerminal(current.state) || Date.parse(current.expiresAt) > this.now()) return current;
+      const now = this.nowIso();
+      const next = {
+        ...current,
+        revision: current.revision + 1,
+        state: "expired",
+        updatedAt: now,
+        terminalAt: now,
+        executionMayHaveOccurred: current.state === "claimed"
+      };
+      if (await this.cas(key, current.revision, next)) return next;
+      const winner = await this.state.get(key);
+      if (winner === null) throw TBError.notFound("device operation not found");
+      current = parseRecord(winner);
+    }
+    throw new TBError("unavailable", "device operation expiry is busy", { retryable: true });
+  }
+  async enforcePendingCap(deviceId) {
+    const prefix = await devicePrefix(deviceId);
+    let cursor;
+    let pending = 0;
+    do {
+      const page = await this.state.list(prefix, {
+        limit: LIST_LIMIT_MAX2,
+        ...cursor === void 0 ? {} : { cursor }
+      });
+      for (const item of page.items) {
+        let record2 = parseRecord(item.value);
+        if (record2.deviceId !== deviceId) continue;
+        record2 = await this.expireRecord(item.key, record2);
+        if (!isTerminal(record2.state)) pending++;
+        if (pending >= this.maxPendingPerDevice) {
+          throw new TBError("rate_limited", "device mailbox pending limit reached", {
+            retryable: true
+          });
+        }
+      }
+      cursor = page.cursor;
+    } while (cursor !== void 0);
+  }
+  async enqueue(input) {
+    const ttlSeconds = input.ttlSeconds ?? this.defaultTtlSeconds;
+    if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > this.maxTtlSeconds) {
+      throw new TBError("invalid_argument", `ttlSeconds must be between 1 and ${this.maxTtlSeconds}`);
+    }
+    const payloadText = canonicalJson({ arguments: input.arguments });
+    if (bytes(payloadText) > this.maxPayloadBytes) {
+      throw new TBError("rate_limited", "device mailbox payload is too large", { retryable: false });
+    }
+    if (input.idempotencyKey !== void 0 && (input.idempotencyKey.length < 1 || input.idempotencyKey.length > 255 || /[\r\n\0]/.test(input.idempotencyKey))) throw new TBError("invalid_argument", "idempotency key is invalid");
+    const binding = input.idempotencyKey === void 0 ? void 0 : canonicalJson({
+      callerOwner: input.caller.owner,
+      deviceId: input.deviceId,
+      targetPath: input.targetPath,
+      idempotencyKey: input.idempotencyKey
+    });
+    const operationId = binding === void 0 ? randomId(this.randomBytes) : await deterministicOperationId(binding);
+    const fingerprint = binding === void 0 ? void 0 : await sha256Hex(canonicalJson({
+      arguments: input.arguments,
+      deviceKeyId: input.deviceKeyId,
+      path: input.path,
+      ttlSeconds
+    }));
+    const key = await stateKey(input.deviceId, operationId);
+    if (binding !== void 0) {
+      const existing2 = await this.state.get(key);
+      if (existing2 !== null) {
+        const record3 = parseRecord(existing2);
+        if (record3.callerOwner !== input.caller.owner || record3.deviceId !== input.deviceId || record3.targetPath !== input.targetPath || record3.idempotencyFingerprint !== fingerprint) throw new TBError("conflict", "idempotency key is bound to another operation");
+        return await this.detail(record3);
+      }
+    }
+    await this.enforcePendingCap(input.deviceId);
+    const now = this.nowIso();
+    const record2 = {
+      v: 1,
+      revision: 1,
+      operationId,
+      commandId: operationId,
+      deviceId: input.deviceId,
+      deviceKeyId: input.deviceKeyId,
+      mountPath: input.mountPath,
+      targetPath: input.targetPath,
+      path: input.path,
+      callerKeyId: input.caller.keyId,
+      callerOwner: input.caller.owner,
+      traceId: input.traceId,
+      createdAt: now,
+      updatedAt: now,
+      expiresAt: new Date(this.now() + ttlSeconds * 1e3).toISOString(),
+      state: "queued",
+      attempt: 0,
+      executionMayHaveOccurred: false,
+      payload: await this.cipher.encrypt(operationId, "payload", { arguments: input.arguments }),
+      ...fingerprint === void 0 ? {} : { idempotencyFingerprint: fingerprint }
+    };
+    if (await this.cas(key, null, record2)) return await this.detail(record2);
+    if (binding === void 0) {
+      throw new TBError("conflict", "device operation id collision", { retryable: true });
+    }
+    const winner = await this.state.get(key);
+    if (winner === null) throw new TBError("conflict", "device operation enqueue conflicted");
+    const existing = parseRecord(winner);
+    if (existing.idempotencyFingerprint !== fingerprint) {
+      throw new TBError("conflict", "idempotency key is bound to another operation");
+    }
+    return await this.detail(existing);
+  }
+  async get(deviceId, operationId) {
+    const { key, record: record2 } = await this.read(deviceId, operationId);
+    return await this.detail(await this.expireRecord(key, record2));
+  }
+  async list(input) {
+    const limit = clampLimit3(input.limit);
+    const states = input.states === void 0 ? void 0 : new Set(input.states);
+    if (states !== void 0 && [...states].some((state) => !isState(state))) {
+      throw new TBError("invalid_argument", "states contains an invalid operation state");
+    }
+    const page = await this.state.list(await devicePrefix(input.deviceId), {
+      limit,
+      ...input.cursor === void 0 ? {} : { cursor: input.cursor }
+    });
+    const items = [];
+    for (const item of page.items) {
+      let record2 = parseRecord(item.value);
+      if (record2.deviceId !== input.deviceId) continue;
+      record2 = await this.expireRecord(item.key, record2);
+      if (states !== void 0 && !states.has(record2.state)) continue;
+      items.push(this.summary(record2));
+    }
+    return { items, ...page.cursor === void 0 ? {} : { cursor: page.cursor } };
+  }
+  async claim(input) {
+    const serverNow = this.nowIso();
+    const page = await this.state.list(await devicePrefix(input.deviceId), {
+      limit: clampLimit3(input.limit),
+      ...input.cursor === void 0 ? {} : { cursor: input.cursor }
+    });
+    for (const item of page.items) {
+      let record2 = parseRecord(item.value);
+      if (record2.deviceId !== input.deviceId || record2.deviceKeyId !== input.deviceKeyId) continue;
+      record2 = await this.expireRecord(item.key, record2);
+      const reclaimable = record2.state === "claimed" && record2.leaseUntil !== void 0 && Date.parse(record2.leaseUntil) <= this.now();
+      if (record2.state !== "queued" && !reclaimable) continue;
+      await input.authorize?.({
+        deviceId: record2.deviceId,
+        deviceKeyId: record2.deviceKeyId,
+        mountPath: record2.mountPath,
+        targetPath: record2.targetPath
+      });
+      const leaseId = randomId(this.randomBytes);
+      const leaseUntil = new Date(Math.min(
+        this.now() + this.leaseSeconds * 1e3,
+        Date.parse(record2.expiresAt)
+      )).toISOString();
+      const next = {
+        ...record2,
+        revision: record2.revision + 1,
+        state: "claimed",
+        attempt: record2.attempt + 1,
+        leaseId,
+        leaseUntil,
+        updatedAt: serverNow
+      };
+      if (!await this.cas(item.key, record2.revision, next)) continue;
+      const payload = await this.cipher.decrypt(
+        record2.operationId,
+        "payload",
+        record2.payload
+      );
+      if (typeof payload !== "object" || payload === null || typeof payload.arguments !== "object" || payload.arguments === null || Array.isArray(payload.arguments)) throw new TBError("internal", "device mailbox payload is invalid", { retryable: false });
+      return {
+        serverNow,
+        ...page.cursor === void 0 ? {} : { cursor: page.cursor },
+        operation: {
+          operationId: next.operationId,
+          commandId: next.commandId,
+          targetPath: next.targetPath,
+          path: next.path,
+          arguments: payload.arguments,
+          caller: { keyId: next.callerKeyId, owner: next.callerOwner },
+          traceId: next.traceId,
+          createdAt: next.createdAt,
+          expiresAt: next.expiresAt,
+          attempt: next.attempt,
+          leaseId,
+          leaseUntil,
+          ...next.cancelRequestedAt === void 0 ? {} : { cancelRequestedAt: next.cancelRequestedAt }
+        }
+      };
+    }
+    return {
+      serverNow,
+      ...page.cursor === void 0 ? {} : { cursor: page.cursor }
+    };
+  }
+  async activeLease(input) {
+    const current = await this.read(input.deviceId, input.operationId);
+    const record2 = await this.expireRecord(current.key, current.record);
+    if (record2.deviceKeyId !== input.deviceKeyId || record2.state !== "claimed" || record2.leaseId !== input.leaseId || record2.leaseUntil === void 0 || Date.parse(record2.leaseUntil) <= this.now()) throw new TBError("conflict", "device operation lease is no longer active");
+    await input.authorize?.({
+      deviceId: record2.deviceId,
+      deviceKeyId: record2.deviceKeyId,
+      mountPath: record2.mountPath,
+      targetPath: record2.targetPath
+    });
+    return { key: current.key, record: record2 };
+  }
+  async renew(input) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+      const { key, record: record2 } = await this.activeLease(input);
+      const serverNow = this.nowIso();
+      const leaseUntil = new Date(Math.min(
+        this.now() + this.leaseSeconds * 1e3,
+        Date.parse(record2.expiresAt)
+      )).toISOString();
+      const next = {
+        ...record2,
+        revision: record2.revision + 1,
+        leaseUntil,
+        updatedAt: serverNow
+      };
+      if (await this.cas(key, record2.revision, next)) {
+        return {
+          serverNow,
+          leaseUntil,
+          ...next.cancelRequestedAt === void 0 ? {} : { cancelRequestedAt: next.cancelRequestedAt }
+        };
+      }
+    }
+    throw new TBError("unavailable", "device operation lease is busy", { retryable: true });
+  }
+  async complete(input, completionInput) {
+    const completion = normalizeCompletion(completionInput);
+    const terminalData = completion.outcome === "succeeded" ? { result: completion.result } : completion.error === void 0 ? {} : { error: completion.error };
+    if (bytes(canonicalJson(terminalData)) > this.maxPayloadBytes) {
+      throw new TBError("rate_limited", "device mailbox terminal payload is too large", {
+        retryable: false
+      });
+    }
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+      const current = await this.read(input.deviceId, input.operationId);
+      let record2 = await this.expireRecord(current.key, current.record);
+      if (record2.deviceKeyId !== input.deviceKeyId) {
+        throw new TBError("conflict", "device operation credential does not match");
+      }
+      await input.authorize?.({
+        deviceId: record2.deviceId,
+        deviceKeyId: record2.deviceKeyId,
+        mountPath: record2.mountPath,
+        targetPath: record2.targetPath
+      });
+      if (isTerminal(record2.state)) {
+        if (record2.completedLeaseId !== input.leaseId || record2.state !== completion.outcome || record2.terminalData === void 0) throw new TBError("conflict", "device operation is already terminal");
+        const existing = await this.cipher.decrypt(
+          record2.operationId,
+          "terminal",
+          record2.terminalData
+        );
+        const requested = completion.outcome === "succeeded" ? { result: completion.result } : completion.error === void 0 ? {} : { error: completion.error };
+        if (canonicalJson(existing) !== canonicalJson(requested)) {
+          throw new TBError("conflict", "device operation completion differs from terminal result");
+        }
+        return await this.detail(record2);
+      }
+      const active = await this.activeLease(input);
+      record2 = active.record;
+      const now = this.nowIso();
+      const next = {
+        ...record2,
+        revision: record2.revision + 1,
+        state: completion.outcome,
+        terminalAt: now,
+        terminalData: await this.cipher.encrypt(record2.operationId, "terminal", terminalData),
+        completedLeaseId: input.leaseId,
+        updatedAt: now
+      };
+      if (await this.cas(active.key, record2.revision, next)) return await this.detail(next);
+    }
+    throw new TBError("unavailable", "device operation completion is busy", { retryable: true });
+  }
+  async cancel(deviceId, operationId) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+      const current = await this.read(deviceId, operationId);
+      const record2 = await this.expireRecord(current.key, current.record);
+      if (isTerminal(record2.state) || record2.cancelRequestedAt !== void 0) {
+        return await this.detail(record2);
+      }
+      const now = this.nowIso();
+      const next = record2.state === "queued" ? {
+        ...record2,
+        revision: record2.revision + 1,
+        state: "cancelled",
+        cancelRequestedAt: now,
+        terminalAt: now,
+        updatedAt: now
+      } : {
+        ...record2,
+        revision: record2.revision + 1,
+        cancelRequestedAt: now,
+        updatedAt: now
+      };
+      if (await this.cas(current.key, record2.revision, next)) return await this.detail(next);
+    }
+    throw new TBError("unavailable", "device operation cancellation is busy", { retryable: true });
+  }
+  async cleanup(opts = {}) {
+    const page = await this.state.list(KEY_DEVICE_OPERATION, {
+      limit: clampLimit3(opts.limit),
+      ...opts.cursor === void 0 ? {} : { cursor: opts.cursor }
+    });
+    let deleted = 0;
+    let expired = 0;
+    for (const item of page.items) {
+      let record2;
+      try {
+        record2 = parseRecord(item.value);
+      } catch {
+        continue;
+      }
+      if (!isTerminal(record2.state) && Date.parse(record2.expiresAt) <= this.now()) {
+        const next = await this.expireRecord(item.key, record2);
+        if (next.state === "expired") expired++;
+        record2 = next;
+      }
+      if (isTerminal(record2.state) && record2.terminalAt !== void 0 && Date.parse(record2.terminalAt) + this.terminalRetentionSeconds * 1e3 <= this.now() && await this.cas(item.key, record2.revision, null)) deleted++;
+    }
+    return {
+      scanned: page.items.length,
+      expired,
+      deleted,
+      ...page.cursor === void 0 ? {} : { cursor: page.cursor }
+    };
+  }
+};
+
 // ../core/src/protocol/errorWire.ts
 var tbErrorCodeSchema = external_exports.enum(TB_ERROR_CODES);
 var tbErrorBodySchema = external_exports.object({
@@ -16620,7 +17285,7 @@ var tbErrorBodySchema = external_exports.object({
 var actionSchema = external_exports.enum(ACTIONS);
 var nodeKindSchema = external_exports.enum(NODE_KINDS);
 var nodeInputConfigSchema = external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
-  "kind-specific config, e.g. mcp: { url, auth?, authRef? } / http: { endpoint, tools } / context: { provider, bucket, \u2026 } / remote: { baseUrl, skRef }; credentials go by authRef/skRef name, never inline"
+  "kind-specific config, e.g. mcp: { url, auth?, authRef?, oauthClient?: { clientId, clientSecretRef? } } / http: { endpoint, tools } / context: { provider, bucket, \u2026 } / remote: { baseUrl, skRef }; credentials go by SecretStore reference name, never inline"
 );
 var nodeInputVirtualizeSchema = external_exports.strictObject({
   prefix: external_exports.string().optional(),
@@ -16654,6 +17319,7 @@ var helpChildSchema = external_exports.object({
 });
 var helpCommandSchema = external_exports.object({
   confirm: external_exports.boolean().optional(),
+  delivery: external_exports.enum(["realtime", "mailbox", "both"]).optional(),
   effect: external_exports.string().optional(),
   h: external_exports.string().optional(),
   inputSchema: external_exports.unknown().optional(),
@@ -16687,14 +17353,42 @@ var treeJsonSchema = external_exports.lazy(() => external_exports.object({
 }));
 var toolSpecSchema = external_exports.object({
   confirm: external_exports.boolean().optional(),
+  delivery: external_exports.enum(["realtime", "mailbox", "both"]).optional(),
   description: external_exports.string().optional(),
   effect: external_exports.string().optional(),
   inputSchema: external_exports.unknown().optional(),
   name: external_exports.string(),
   outputSchema: external_exports.unknown().optional()
 });
-var toolSearchItemSchema = external_exports.object({
+var toolSearchRelevanceSchema = external_exports.strictObject({
+  coverage: external_exports.number().min(0).max(1),
+  matchedTermCount: external_exports.number().int().nonnegative(),
+  rankingVersion: external_exports.literal("keyword-v2"),
+  totalTermCount: external_exports.number().int().positive()
+}).refine(
+  (value) => value.matchedTermCount <= value.totalTermCount && value.coverage === value.matchedTermCount / value.totalTermCount,
+  { message: "coverage must equal matchedTermCount / totalTermCount" }
+);
+var toolSearchSourceSchema = external_exports.strictObject({
+  path: external_exports.string()
+});
+var toolSearchSourceResultSchema = external_exports.strictObject({
   path: external_exports.string(),
+  status: external_exports.enum([
+    "ok",
+    "unsupported",
+    "timed_out",
+    "unavailable",
+    "cycle",
+    "hop_limit",
+    "budget_exhausted",
+    "invalid_response"
+  ])
+});
+var toolSearchItemSchema = external_exports.strictObject({
+  path: external_exports.string(),
+  relevance: toolSearchRelevanceSchema,
+  source: toolSearchSourceSchema.optional(),
   tool: toolSpecSchema
 });
 function pageSchema(itemSchema) {
@@ -16703,19 +17397,136 @@ function pageSchema(itemSchema) {
     items: external_exports.array(itemSchema)
   });
 }
-var toolSearchPageSchema = pageSchema(toolSearchItemSchema);
+var toolSearchPageSchema = external_exports.strictObject({
+  cursor: external_exports.string().optional(),
+  items: external_exports.array(toolSearchItemSchema),
+  partial: external_exports.boolean().optional(),
+  snapshot: external_exports.string().optional(),
+  sources: external_exports.array(toolSearchSourceResultSchema).optional()
+});
 var toolSearchRequestSchema = external_exports.strictObject({
   opts: external_exports.strictObject({
     cursor: external_exports.string().optional(),
+    detail: external_exports.enum(["compact", "full"]).optional(),
+    effects: external_exports.array(external_exports.enum(["read", "write", "destructive", "unknown"])).min(1).optional(),
+    federation: external_exports.enum(["local", "recursive"]).optional(),
     limit: external_exports.number().int().optional(),
-    mode: external_exports.enum(["keyword", "semantic"]).optional()
+    matching: external_exports.enum(["best", "all"]).optional(),
+    minCoverage: external_exports.number().gt(0).max(1).optional(),
+    mode: external_exports.enum(["keyword", "semantic"]).optional(),
+    pathPrefix: external_exports.string().optional()
   }).optional(),
   query: external_exports.string().trim().min(1)
 });
+var deviceOperationStateSchema = external_exports.enum(
+  DEVICE_OPERATION_STATES
+);
+var deviceOperationCallerSchema = external_exports.object({
+  keyId: external_exports.string().min(1),
+  owner: external_exports.string().min(1)
+});
+var deviceOperationSummaryShape = {
+  attempt: external_exports.number().int().nonnegative(),
+  caller: deviceOperationCallerSchema,
+  cancelRequestedAt: external_exports.iso.datetime({ offset: true }).optional(),
+  commandId: external_exports.string().min(1),
+  createdAt: external_exports.iso.datetime({ offset: true }),
+  deviceId: external_exports.string().min(1),
+  executionMayHaveOccurred: external_exports.boolean(),
+  expiresAt: external_exports.iso.datetime({ offset: true }),
+  leaseUntil: external_exports.iso.datetime({ offset: true }).optional(),
+  mountPath: external_exports.string().min(1),
+  operationId: external_exports.string().min(1),
+  state: deviceOperationStateSchema,
+  targetPath: external_exports.string().min(1),
+  terminalAt: external_exports.iso.datetime({ offset: true }).optional(),
+  traceId: external_exports.string().min(1),
+  updatedAt: external_exports.iso.datetime({ offset: true })
+};
+var deviceOperationSummarySchema = external_exports.object(
+  deviceOperationSummaryShape
+);
+var deviceOperationDetailSchema = external_exports.object({
+  ...deviceOperationSummaryShape,
+  error: tbErrorBodySchema.optional(),
+  result: external_exports.json().optional()
+});
+var deviceOperationListRequestSchema = external_exports.strictObject({
+  deviceId: external_exports.string().min(1),
+  opts: external_exports.strictObject({
+    cursor: external_exports.string().min(1).optional(),
+    limit: external_exports.number().int().positive().optional(),
+    states: external_exports.array(deviceOperationStateSchema).min(1).optional()
+  }).optional()
+});
+var deviceOperationListResponseSchema = pageSchema(deviceOperationSummarySchema);
+var deviceOperationIdentityRequestSchema = external_exports.strictObject({
+  deviceId: external_exports.string().min(1),
+  operationId: external_exports.string().min(1)
+});
+var deviceOperationClaimRequestSchema = external_exports.strictObject({
+  cursor: external_exports.string().min(1).optional(),
+  deviceId: external_exports.string().min(1),
+  limit: external_exports.number().int().positive().optional()
+});
+var deviceOperationClaimSchema = external_exports.object({
+  arguments: external_exports.record(external_exports.string(), external_exports.json()),
+  attempt: external_exports.number().int().positive(),
+  caller: deviceOperationCallerSchema,
+  cancelRequestedAt: external_exports.iso.datetime({ offset: true }).optional(),
+  commandId: external_exports.string().min(1),
+  createdAt: external_exports.iso.datetime({ offset: true }),
+  expiresAt: external_exports.iso.datetime({ offset: true }),
+  leaseId: external_exports.string().min(1),
+  leaseUntil: external_exports.iso.datetime({ offset: true }),
+  operationId: external_exports.string().min(1),
+  path: external_exports.string().min(1),
+  targetPath: external_exports.string().min(1),
+  traceId: external_exports.string().min(1)
+});
+var deviceOperationClaimResponseSchema = external_exports.object({
+  cursor: external_exports.string().optional(),
+  operation: deviceOperationClaimSchema.optional(),
+  serverNow: external_exports.iso.datetime({ offset: true })
+});
+var deviceOperationLeaseShape = {
+  deviceId: external_exports.string().min(1),
+  leaseId: external_exports.string().min(1),
+  operationId: external_exports.string().min(1)
+};
+var deviceOperationRenewRequestSchema = external_exports.strictObject(deviceOperationLeaseShape);
+var deviceOperationRenewResponseSchema = external_exports.object({
+  cancelRequestedAt: external_exports.iso.datetime({ offset: true }).optional(),
+  leaseUntil: external_exports.iso.datetime({ offset: true }),
+  serverNow: external_exports.iso.datetime({ offset: true })
+});
+var deviceOperationCompleteRequestSchema = external_exports.discriminatedUnion("outcome", [
+  external_exports.strictObject({
+    ...deviceOperationLeaseShape,
+    outcome: external_exports.literal("succeeded"),
+    result: external_exports.json()
+  }),
+  external_exports.strictObject({
+    ...deviceOperationLeaseShape,
+    error: tbErrorBodySchema,
+    outcome: external_exports.literal("rejected")
+  }),
+  external_exports.strictObject({
+    ...deviceOperationLeaseShape,
+    error: tbErrorBodySchema,
+    outcome: external_exports.literal("failed")
+  }),
+  external_exports.strictObject({
+    ...deviceOperationLeaseShape,
+    error: tbErrorBodySchema.optional(),
+    outcome: external_exports.literal("result_unknown")
+  })
+]);
 var registryNodeSchema = external_exports.object({
   config: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
   createdAt: external_exports.string().optional(),
   description: external_exports.string(),
+  deviceId: external_exports.string().optional(),
   kind: nodeKindSchema,
   lastSeenAt: external_exports.string().optional(),
   online: external_exports.boolean().optional(),
@@ -17164,7 +17975,7 @@ async function objectBodyToBytes(body) {
   if (body instanceof ArrayBuffer) return new Uint8Array(body);
   return readStreamBytes(body);
 }
-function bytesToObjectStream(bytes) {
+function bytesToObjectStream(bytes2) {
   return {
     getReader() {
       let done = false;
@@ -17172,7 +17983,7 @@ function bytesToObjectStream(bytes) {
         async read() {
           if (done) return { done: true };
           done = true;
-          return { done: false, value: bytes };
+          return { done: false, value: bytes2 };
         },
         releaseLock() {
         },
@@ -17297,7 +18108,7 @@ async function createObjectContextUploadGrant(store, opts, input) {
     expiresAt
   };
 }
-function clampLimit3(limit) {
+function clampLimit4(limit) {
   if (limit === void 0) return LIST_LIMIT_DEFAULT;
   if (!Number.isInteger(limit) || limit < 1) {
     throw new TBError("invalid_argument", `limit \u975E\u6CD5:${limit}`);
@@ -17371,7 +18182,7 @@ function createObjectContextProvider(store, opts) {
   return {
     async list(path, listOpts) {
       rejectFilter(listOpts);
-      const limit = clampLimit3(listOpts?.limit);
+      const limit = clampLimit4(listOpts?.limit);
       const rel = path === "" ? "" : `${normalizeEntryPath(path)}/`;
       const full = keyPrefix + rel;
       assertContextKeyAllowed(full.slice(0, -1), path, false);
@@ -17481,7 +18292,7 @@ function createObjectContextProvider(store, opts) {
         throw new TBError("invalid_argument", "query \u4E0D\u80FD\u4E3A\u7A7A");
       }
       rejectFilter(searchOpts);
-      const limit = clampLimit3(searchOpts?.limit);
+      const limit = clampLimit4(searchOpts?.limit);
       const q = query.toLowerCase();
       const after = searchOpts?.cursor;
       const items = [];
@@ -17538,6 +18349,7 @@ function isContextExpired(createdAt, ttlSec, now) {
 // ../core/src/device/frames.ts
 var deviceNodeCmdSchema = external_exports.object({
   name: external_exports.string().min(1),
+  delivery: external_exports.enum(["realtime", "mailbox", "both"]).optional(),
   description: external_exports.string().optional(),
   inputSchema: external_exports.unknown().optional(),
   outputSchema: external_exports.unknown().optional(),
@@ -17669,7 +18481,7 @@ function deviceShellHelpModel(nodePath, shell = {}) {
         timeoutMs: { type: "number", description: "kill the command after this many ms" }
       }
     },
-    returns: "{ stdout, stderr, exitCode }",
+    returns: "{ stdout, stderr, exitCode, startedAt, completedAt, outcome, signal?, stdoutTruncated, stderrTruncated }",
     scope: "call",
     effect: "destructive",
     confirm: true
@@ -17804,7 +18616,7 @@ var DeviceGatewaySession = class {
   call(req, done) {
     const cached2 = this.results.get(req.id);
     if (cached2 !== void 0) {
-      done(cached2);
+      done(cached2, "completed");
       return;
     }
     const inflight = this.pending.get(req.id);
@@ -17813,19 +18625,28 @@ var DeviceGatewaySession = class {
       return;
     }
     if (this.phase_ !== "ready") {
-      done({ ok: false, error: TBError.deviceOffline().toJSON() });
+      done({ ok: false, error: TBError.deviceOffline().toJSON() }, "not_dispatched");
       return;
     }
     const cancelTimer = this.opts.setTimer(() => this.onCallTimeout(req.id), this.timeoutMs);
     this.pending.set(req.id, { waiters: [done], cancelTimer });
-    this.io.send({
-      type: "call",
-      id: req.id,
-      path: req.path,
-      arguments: req.arguments,
-      // undefined 经 JSON.stringify 丢弃:老网关不带 context 时帧形状不变。
-      ...req.context !== void 0 ? { context: req.context } : {}
-    });
+    try {
+      this.io.send({
+        type: "call",
+        id: req.id,
+        path: req.path,
+        arguments: req.arguments,
+        // undefined 经 JSON.stringify 丢弃:老网关不带 context 时帧形状不变。
+        ...req.context !== void 0 ? { context: req.context } : {}
+      });
+    } catch {
+      this.pending.delete(req.id);
+      cancelTimer();
+      done({
+        ok: false,
+        error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u53D1\u9001\u5931\u8D25", { retryable: true }).toJSON()
+      }, "unknown");
+    }
   }
   /** 幂等表回放种子(DO 从 ctx.storage 恢复时用);已有同 id 结果则忽略。 */
   seedResult(id, result) {
@@ -17845,7 +18666,7 @@ var DeviceGatewaySession = class {
     };
     for (const entry of entries) {
       entry.cancelTimer();
-      for (const waiter of entry.waiters) waiter(result);
+      for (const waiter of entry.waiters) waiter(result, "unknown");
     }
   }
   protocolReject(message) {
@@ -17859,7 +18680,7 @@ var DeviceGatewaySession = class {
     if (entry === void 0) return;
     this.pending.delete(id);
     entry.cancelTimer();
-    for (const waiter of entry.waiters) waiter(result);
+    for (const waiter of entry.waiters) waiter(result, "completed");
   }
   onCallTimeout(id) {
     const entry = this.pending.get(id);
@@ -17872,7 +18693,7 @@ var DeviceGatewaySession = class {
         retryable: true
       }).toJSON()
     };
-    for (const waiter of entry.waiters) waiter(result);
+    for (const waiter of entry.waiters) waiter(result, "unknown");
   }
 };
 
@@ -17946,10 +18767,10 @@ function toView(entry) {
 }
 var ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 function randomFeedbackId() {
-  const bytes = new Uint8Array(6);
-  crypto.getRandomValues(bytes);
+  const bytes2 = new Uint8Array(6);
+  crypto.getRandomValues(bytes2);
   let out = "fb_";
-  for (const b of bytes) out += ID_ALPHABET[b % ID_ALPHABET.length];
+  for (const b of bytes2) out += ID_ALPHABET[b % ID_ALPHABET.length];
   return out;
 }
 function requireShort(value, field, max) {
@@ -18094,6 +18915,7 @@ function renderHelpDsl(model) {
     if (cmd.outputSchema !== void 0) lines.push(`  result ${JSON.stringify(cmd.outputSchema)}`);
     if (cmd.returns !== void 0) lines.push(...attrLines("returns", cmd.returns));
     lines.push(`  scope ${cmd.scope}`);
+    if (cmd.delivery !== void 0) lines.push(`  delivery ${cmd.delivery}`);
     if (cmd.effect !== void 0) lines.push(`  effect ${cmd.effect}`);
     if (cmd.confirm) lines.push("  confirm");
   }
@@ -18126,6 +18948,7 @@ function renderHelpJson(model) {
     if (cmd.inputSchema !== void 0) out.inputSchema = cmd.inputSchema;
     if (cmd.outputSchema !== void 0) out.outputSchema = cmd.outputSchema;
     if (cmd.returns !== void 0) out.returns = cmd.returns;
+    if (cmd.delivery !== void 0) out.delivery = cmd.delivery;
     if (cmd.effect !== void 0) out.effect = cmd.effect;
     if (cmd.confirm) out.confirm = cmd.confirm;
     return out;
@@ -18165,6 +18988,7 @@ function cmdSection(cmd, index) {
   }
   lines.push(`- Invoke: \`POST ${cmd.path}\` with body \`{...arguments}\``);
   lines.push(`- Required scope: \`${cmd.scope}\``);
+  if (cmd.delivery !== void 0) lines.push(`- Delivery: \`${cmd.delivery}\``);
   if (cmd.effect !== void 0) {
     lines.push(
       `- Effect: \`${cmd.effect}\`${cmd.confirm ? " \u2014 **ask the user to confirm before calling**" : ""}`
@@ -18382,7 +19206,7 @@ var KEY_STORE_IDEMPOTENCY = "store:idempotency:";
 var UPLOAD_TTL_SEC_DEFAULT = 15 * 60;
 var SHARE_TTL_SEC_DEFAULT = 15 * 60;
 var MAX_OBJECT_BYTES_DEFAULT = 256 * 1024 * 1024;
-var MAX_CAS_ATTEMPTS = 32;
+var MAX_CAS_ATTEMPTS2 = 32;
 var CAPABILITY_TTL_SEC_MAX = 7 * 24 * 60 * 60;
 var TOKEN_PREFIX = {
   call: "tbc",
@@ -18732,7 +19556,7 @@ var StoreService = class {
   }
   async revokeCallUploadCapability(token) {
     const id = this.tokenId(token, "call");
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const raw = await this.state.get(`${KEY_STORE_CALL_CAPABILITY}${id}`);
       if (raw === null) throw new TBError("permission_denied", "call upload capability \u65E0\u6548");
       const capability = parseCallCapability(raw);
@@ -18946,7 +19770,7 @@ var StoreService = class {
   }
   async delete(uri, actor) {
     const { objectId } = parseStoreUri(uri);
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const object2 = await this.requireObject(objectId);
       if (!actor.admin && object2.owner !== actor.owner) {
         throw new TBError("not_found", "Store \u5BF9\u8C61\u4E0D\u5B58\u5728");
@@ -19010,7 +19834,7 @@ var StoreService = class {
   }
   async revokeShare(shareId, actor) {
     const owner = requireOwner(actor);
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const raw = await this.state.get(`${KEY_STORE_SHARE}${shareId}`);
       if (raw === null) throw new TBError("not_found", "share grant \u4E0D\u5B58\u5728");
       const grant = parseShare(raw);
@@ -19334,7 +20158,7 @@ var StoreService = class {
     await this.compareRecord(resolved.key, resolved.binding, null);
   }
   async reserveCallCapability(token, objectId, input, transportMaxBytes) {
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const capability = await this.verifyCallUploadCapability(token);
       const previous = capability.reservations.find((r) => r.objectId === objectId);
       if (previous !== void 0) {
@@ -19456,7 +20280,7 @@ var StoreService = class {
   }
   /** driver DELETE 成功后持久化证据；后续 cleanup 只收 tombstone，不再重复外部 DELETE。 */
   async markBytesDeleted(objectId, expectedDriverKey) {
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const raw = await this.state.get(`${KEY_STORE_OBJECT}${objectId}`);
       if (raw === null) return;
       const object2 = parseObject(raw);
@@ -19556,7 +20380,7 @@ var StoreService = class {
   }
   async markReady(sessionInput, meta3) {
     const actualChecksum = sessionInput.expectedChecksum !== void 0 && meta3.metadata?.["checksum-sha256"]?.toLowerCase() === sessionInput.expectedChecksum.value ? sessionInput.expectedChecksum : void 0;
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const object2 = await this.requireObject(sessionInput.objectId);
       if (object2.status === "ready") {
         await this.completeSessionBestEffort(await this.requireSession(sessionInput.id));
@@ -19586,7 +20410,7 @@ var StoreService = class {
     throw new TBError("conflict", "\u5BF9\u8C61\u5E76\u53D1\u72B6\u6001\u51B2\u7A81:pending");
   }
   async completeSessionBestEffort(sessionInput) {
-    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS2; attempt++) {
       const session = await this.requireSession(sessionInput.id);
       if (session.status === "completed" || session.status !== "created") return;
       const completedAt = this.nowIso();
@@ -19762,8 +20586,8 @@ function canonicalCatalogJson(value) {
   return JSON.stringify(normalize(value));
 }
 async function catalogDigest(value) {
-  const bytes = new TextEncoder().encode(canonicalCatalogJson(value));
-  const hash2 = await crypto.subtle.digest("SHA-256", bytes);
+  const bytes2 = new TextEncoder().encode(canonicalCatalogJson(value));
+  const hash2 = await crypto.subtle.digest("SHA-256", bytes2);
   return [...new Uint8Array(hash2)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 async function catalogSetDigest(catalog) {
@@ -19957,11 +20781,11 @@ var pluginCallSchema = external_exports.object({
   arguments: external_exports.record(external_exports.string(), external_exports.unknown())
 });
 function assertPluginPayloadSize(payload) {
-  const bytes = new TextEncoder().encode(payload).length;
-  if (bytes > PLUGIN_PAYLOAD_MAX_BYTES) {
+  const bytes2 = new TextEncoder().encode(payload).length;
+  if (bytes2 > PLUGIN_PAYLOAD_MAX_BYTES) {
     throw new TBError(
       "invalid_argument",
-      `payload ${bytes} \u5B57\u8282\u8D85\u8FC7\u4E0A\u9650 ${PLUGIN_PAYLOAD_MAX_BYTES}(\u2264 1 MiB;\u66F4\u5927\u5185\u5BB9\u7ECF $ref)`
+      `payload ${bytes2} \u5B57\u8282\u8D85\u8FC7\u4E0A\u9650 ${PLUGIN_PAYLOAD_MAX_BYTES}(\u2264 1 MiB;\u66F4\u5927\u5185\u5BB9\u7ECF $ref)`
     );
   }
 }
@@ -20000,6 +20824,13 @@ var positiveEnvKeys = [
   "TB_MAX_HOPS",
   "TB_REF_THRESHOLD_BYTES",
   "TB_REF_TTL_SEC",
+  "TB_SEARCH_FEDERATION_CONCURRENCY",
+  "TB_SEARCH_FEDERATION_DEADLINE_MS",
+  "TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES",
+  "TB_SEARCH_FEDERATION_MAX_SOURCES",
+  "TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS",
+  "TB_SEARCH_FEDERATION_RETURN_RESERVE_MS",
+  "TB_SEARCH_FEDERATION_SESSION_TTL_SEC",
   "TB_STORE_CALL_MAX_BYTES",
   "TB_STORE_CALL_MAX_OBJECT_BYTES",
   "TB_STORE_CALL_MAX_OBJECTS",
@@ -20047,6 +20878,15 @@ function parseRuntimeEnv(env) {
     remote: {
       allowInsecure: allowInsecureHttp,
       allowlist,
+      federatedSearch: {
+        ...parsed.TB_SEARCH_FEDERATION_CONCURRENCY === void 0 ? {} : { maxConcurrency: parsed.TB_SEARCH_FEDERATION_CONCURRENCY },
+        ...parsed.TB_SEARCH_FEDERATION_DEADLINE_MS === void 0 ? {} : { totalDeadlineMs: parsed.TB_SEARCH_FEDERATION_DEADLINE_MS },
+        ...parsed.TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES === void 0 ? {} : { maxResponseBodyBytes: parsed.TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES },
+        ...parsed.TB_SEARCH_FEDERATION_MAX_SOURCES === void 0 ? {} : { maxSources: parsed.TB_SEARCH_FEDERATION_MAX_SOURCES },
+        ...parsed.TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS === void 0 ? {} : { minChildWorkMs: parsed.TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS },
+        ...parsed.TB_SEARCH_FEDERATION_RETURN_RESERVE_MS === void 0 ? {} : { perHopReturnReserveMs: parsed.TB_SEARCH_FEDERATION_RETURN_RESERVE_MS },
+        ...parsed.TB_SEARCH_FEDERATION_SESSION_TTL_SEC === void 0 ? {} : { sessionTtlMs: parsed.TB_SEARCH_FEDERATION_SESSION_TTL_SEC * 1e3 }
+      },
       maxHops: parsed.TB_MAX_HOPS ?? DEFAULT_MAX_HOPS,
       ...parsed.TB_INSTANCE_ID ? { instanceId: parsed.TB_INSTANCE_ID } : {}
     }
@@ -20095,26 +20935,37 @@ var TOOL_SEARCH_SNAPSHOT_CHUNKS_MAX = Math.ceil(
 var TOOL_SEARCH_REBUILD_CHUNKS_MAX = TOOL_SEARCH_SOURCE_CHUNKS_MAX + TOOL_SEARCH_SNAPSHOT_CHUNKS_MAX;
 var TOOL_SEARCH_TERM_LIMIT = 32;
 var TOOL_SEARCH_UNIT_LIMIT = 98;
+var TOOL_SEARCH_LIMIT_DEFAULT = 10;
 var TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX = 50;
 var TOOL_SEARCH_QUERY_MAX = 1024;
+var TOOL_SEARCH_RANKING_VERSION = "keyword-v2";
 var TOOL_SEARCH_CURSOR_OFFSET_MAX = 1e6;
+var TOOL_SEARCH_EFFECTS = [
+  "read",
+  "write",
+  "destructive",
+  "unknown"
+];
 function assertKeywordToolSearchMode(opts) {
   if (opts?.mode !== void 0 && opts.mode !== "keyword") {
     throw new TBError("invalid_argument", `SearchIndex \u4E0D\u652F\u6301 mode '${String(opts.mode)}'`);
   }
 }
 function normalizeToolSearchLimit(limit) {
-  if (limit === void 0) return LIST_LIMIT_DEFAULT;
+  if (limit === void 0) return TOOL_SEARCH_LIMIT_DEFAULT;
   if (typeof limit !== "number" || !Number.isFinite(limit) || !Number.isInteger(limit)) {
     throw new TBError("invalid_argument", "opts.limit \u5FC5\u987B\u662F\u6574\u6570");
   }
-  if (limit < 1) return LIST_LIMIT_DEFAULT;
+  if (limit < 1) return TOOL_SEARCH_LIMIT_DEFAULT;
   return Math.min(limit, LIST_LIMIT_MAX);
 }
+function searchUnitAllowsPath(unit) {
+  return !/^%[A-Za-z0-9]{1,2}%$/u.test(unit.pattern);
+}
 function stableDigest(value) {
-  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  const bytes2 = new TextEncoder().encode(JSON.stringify(value));
   let hash2 = 0xcbf29ce484222325n;
-  for (const byte of bytes) {
+  for (const byte of bytes2) {
     hash2 ^= BigInt(byte);
     hash2 = BigInt.asUintN(64, hash2 * 0x100000001b3n);
   }
@@ -20124,12 +20975,12 @@ function truncateUtf8(value, maxBytes) {
   const encoder = new TextEncoder();
   if (encoder.encode(value).length <= maxBytes) return value;
   let result = "";
-  let bytes = 0;
+  let bytes2 = 0;
   for (const char of value) {
     const size = encoder.encode(char).length;
-    if (bytes + size > maxBytes) break;
+    if (bytes2 + size > maxBytes) break;
     result += char;
-    bytes += size;
+    bytes2 += size;
   }
   return result;
 }
@@ -20154,6 +21005,7 @@ function serializedRecord(path, tool, feedback) {
   }
   const record2 = {
     description: truncateUtf8(tool.description ?? "", TOOL_SEARCH_DESCRIPTION_BYTES_MAX),
+    effect: TOOL_SEARCH_EFFECTS.includes(tool.effect) ? tool.effect : "unknown",
     feedback,
     name: tool.name,
     path,
@@ -20164,17 +21016,70 @@ function serializedRecord(path, tool, feedback) {
 function jsonPayload(record2) {
   return {
     description: record2.description,
+    effect: record2.effect,
     feedback: record2.feedback,
     name: record2.name,
     path: record2.path
   };
 }
 function normalizeToolSearchPath(path) {
-  const canonical = normalizePath(path);
+  const canonical = canonicalizePath(path);
   const pathError = validatePath(canonical);
   if (pathError !== null) throw pathError;
   return canonical;
 }
+function normalizeToolSearchOptions(opts) {
+  let effects;
+  if (opts?.effects !== void 0) {
+    if (!Array.isArray(opts.effects) || opts.effects.length === 0) {
+      throw new TBError("invalid_argument", "opts.effects \u5FC5\u987B\u662F\u975E\u7A7A\u6570\u7EC4");
+    }
+    const selected = /* @__PURE__ */ new Set();
+    for (const effect of opts.effects) {
+      if (!TOOL_SEARCH_EFFECTS.includes(effect)) {
+        throw new TBError("invalid_argument", `opts.effects \u542B\u975E\u6CD5 effect '${String(effect)}'`);
+      }
+      selected.add(effect);
+    }
+    effects = TOOL_SEARCH_EFFECTS.filter((effect) => selected.has(effect));
+  }
+  const matching = opts?.matching ?? "best";
+  if (matching !== "best" && matching !== "all") {
+    throw new TBError("invalid_argument", `opts.matching '${String(matching)}' \u975E\u6CD5`);
+  }
+  let minCoverage = opts?.minCoverage;
+  if (minCoverage !== void 0 && (typeof minCoverage !== "number" || !Number.isFinite(minCoverage) || minCoverage <= 0 || minCoverage > 1)) {
+    throw new TBError("invalid_argument", "opts.minCoverage \u5FC5\u987B\u5927\u4E8E 0 \u4E14\u4E0D\u8D85\u8FC7 1");
+  }
+  if (matching === "all") {
+    if (minCoverage !== void 0 && minCoverage !== 1) {
+      throw new TBError("invalid_argument", "opts.matching='all' \u53EA\u5141\u8BB8 minCoverage=1");
+    }
+    minCoverage = 1;
+  }
+  let pathPrefix;
+  if (opts?.pathPrefix !== void 0) {
+    if (typeof opts.pathPrefix !== "string") {
+      throw new TBError("invalid_argument", "opts.pathPrefix \u5FC5\u987B\u662F\u8DEF\u5F84\u5B57\u7B26\u4E32");
+    }
+    pathPrefix = normalizeToolSearchPath(opts.pathPrefix);
+  }
+  return {
+    ...effects === void 0 ? {} : { effects },
+    matching,
+    ...minCoverage === void 0 ? {} : { minCoverage },
+    ...pathPrefix === void 0 ? {} : { pathPrefix }
+  };
+}
+function toolSearchOptionsFingerprint(opts) {
+  const normalized = normalizeToolSearchOptions(opts);
+  return stableDigest([
+    normalized.effects ?? null,
+    normalized.matching,
+    normalized.minCoverage ?? null,
+    normalized.pathPrefix ?? null
+  ]);
+}
 function serializeToolSearchSnapshot(path, tools, feedback = "") {
   const canonical = normalizeToolSearchPath(path);
   const names = /* @__PURE__ */ new Set();
@@ -20230,6 +21135,7 @@ function toolSearchSnapshotDigest(records) {
     record2.path,
     record2.name,
     record2.description,
+    record2.effect,
     record2.feedback,
     record2.toolDigest
   ]));
@@ -20279,54 +21185,93 @@ function scriptRuns(term) {
   }
   return runs;
 }
-function addSearchUnit(units, value, tier) {
+function addSearchUnit(units, value, tier, logicalTermId) {
   const pattern = likePattern(value);
   if (new TextEncoder().encode(pattern).length > TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX) return false;
-  const existing = units.get(pattern);
+  const key = `${logicalTermId}\0${pattern}`;
+  const existing = units.get(key);
   if (existing === void 0 || tier > existing.tier) {
-    units.set(pattern, { pattern, tier });
+    units.set(key, { logicalTermId, pattern, tier });
   }
   return true;
 }
-function addChunkedSearchUnits(units, value, tier) {
+function addChunkedSearchUnits(units, value, tier, logicalTermId) {
   let chunk = "";
   for (const codePoint of value) {
     if (likePatternBytes(chunk + codePoint) <= TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX) {
       chunk += codePoint;
       continue;
     }
-    if (chunk.length > 0) addSearchUnit(units, chunk, tier);
+    if (chunk.length > 0) addSearchUnit(units, chunk, tier, logicalTermId);
     chunk = codePoint;
   }
-  if (chunk.length > 0) addSearchUnit(units, chunk, tier);
+  if (chunk.length > 0) addSearchUnit(units, chunk, tier, logicalTermId);
 }
-function prepareToolSearchUnits(query) {
-  const terms = normalizeToolSearchQuery(query).split(/\s+/u);
-  if (terms.length > TOOL_SEARCH_TERM_LIMIT) {
+function prepareToolSearchQuery(query, unitLimit = TOOL_SEARCH_UNIT_LIMIT) {
+  if (!Number.isInteger(unitLimit) || unitLimit < 1 || unitLimit > TOOL_SEARCH_UNIT_LIMIT) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 unit limit \u975E\u6CD5");
+  }
+  const rawTerms = normalizeToolSearchQuery(query).split(/\s+/u);
+  if (rawTerms.length > TOOL_SEARCH_TERM_LIMIT) {
     throw new TBError("invalid_argument", `\u641C\u7D22 query \u6700\u591A ${TOOL_SEARCH_TERM_LIMIT} \u4E2A terms`);
   }
+  const seenTerms = /* @__PURE__ */ new Set();
+  const terms = rawTerms.filter((term) => {
+    const key = term.replace(/[A-Z]/g, (char) => char.toLowerCase());
+    if (seenTerms.has(key)) return false;
+    seenTerms.add(key);
+    return true;
+  });
+  if (terms.length > unitLimit) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 unit limit \u65E0\u6CD5\u8986\u76D6\u5168\u90E8 logical terms");
+  }
   const units = /* @__PURE__ */ new Map();
-  for (const term of terms) {
-    const wholeAdded = addSearchUnit(units, term, 4);
+  for (const [logicalTermId, term] of terms.entries()) {
+    const wholeAdded = addSearchUnit(units, term, 4, logicalTermId);
     const runs = scriptRuns(term);
     if (runs.length > 1) {
       for (const run of runs) {
         const value = run.codePoints.join("");
-        if (run.cjk) addSearchUnit(units, value, 2);
-        else addChunkedSearchUnits(units, value, 2);
+        if (run.cjk) addSearchUnit(units, value, 2, logicalTermId);
+        else addChunkedSearchUnits(units, value, 2, logicalTermId);
       }
     } else if (!wholeAdded && runs[0]?.cjk === false) {
-      addChunkedSearchUnits(units, term, 2);
+      addChunkedSearchUnits(units, term, 2, logicalTermId);
     }
     for (const run of runs) {
       if (!run.cjk) continue;
       for (let index = 0; index < run.codePoints.length - 1; index += 1) {
-        addSearchUnit(units, run.codePoints.slice(index, index + 2).join(""), 2);
+        addSearchUnit(
+          units,
+          run.codePoints.slice(index, index + 2).join(""),
+          2,
+          logicalTermId
+        );
+      }
+      for (const codePoint of run.codePoints) {
+        addSearchUnit(units, codePoint, 1, logicalTermId);
       }
-      for (const codePoint of run.codePoints) addSearchUnit(units, codePoint, 1);
     }
   }
-  return [...units.values()].sort((left, right) => right.tier - left.tier).slice(0, TOOL_SEARCH_UNIT_LIMIT);
+  const ordered = [...units.values()].sort((left, right) => right.tier - left.tier);
+  if (ordered.length <= unitLimit) {
+    return { totalTermCount: terms.length, units: ordered };
+  }
+  const selected = /* @__PURE__ */ new Set();
+  const represented = /* @__PURE__ */ new Set();
+  for (const unit of ordered) {
+    if (represented.has(unit.logicalTermId)) continue;
+    represented.add(unit.logicalTermId);
+    selected.add(unit);
+  }
+  for (const unit of ordered) {
+    if (selected.size >= unitLimit) break;
+    selected.add(unit);
+  }
+  return {
+    totalTermCount: terms.length,
+    units: ordered.filter((unit) => selected.has(unit))
+  };
 }
 function cursorBase64UrlDecode(value) {
   if (value.length === 0 || value.length > 4096) {
@@ -20353,13 +21298,15 @@ async function cursorCryptoKey(secret) {
     ["encrypt", "decrypt"]
   );
 }
-async function encodeToolSearchCursor(query, mode, revision, offset, secret) {
+async function sealToolSearchCursor(query, mode, revision, offset, secret, optionsFingerprint) {
   const payload = {
+    f: optionsFingerprint,
     h: stableDigest(normalizeToolSearchQuery(query)),
+    k: TOOL_SEARCH_RANKING_VERSION,
     m: mode,
     o: offset,
     r: revision,
-    v: 1
+    v: 2
   };
   const iv = crypto.getRandomValues(new Uint8Array(12));
   const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
@@ -20372,7 +21319,17 @@ async function encodeToolSearchCursor(query, mode, revision, offset, secret) {
   sealed.set(ciphertext, iv.length);
   return base64urlEncode(sealed);
 }
-async function decodeToolSearchCursor(cursor, query, mode, revision, secret) {
+async function encodeToolSearchCursor(query, mode, revision, offset, secret, opts) {
+  return await sealToolSearchCursor(
+    query,
+    mode,
+    revision,
+    offset,
+    secret,
+    toolSearchOptionsFingerprint(opts)
+  );
+}
+async function decodeToolSearchCursor(cursor, query, mode, revision, secret, opts) {
   if (cursor === void 0) return 0;
   let value;
   try {
@@ -20393,115 +21350,199 @@ async function decodeToolSearchCursor(cursor, query, mode, revision, secret) {
   }
   const payload = value;
   const keys = Object.keys(payload).sort().join(",");
-  if (keys !== "h,m,o,r,v" || payload.v !== 1 || payload.h !== stableDigest(normalizeToolSearchQuery(query)) || payload.m !== mode || payload.r !== revision || !Number.isSafeInteger(payload.o) || (payload.o ?? -1) < 0 || (payload.o ?? 0) > TOOL_SEARCH_CURSOR_OFFSET_MAX) {
+  if (keys !== "f,h,k,m,o,r,v" || payload.v !== 2 || payload.k !== TOOL_SEARCH_RANKING_VERSION || payload.f !== toolSearchOptionsFingerprint(opts) || payload.h !== stableDigest(normalizeToolSearchQuery(query)) || payload.m !== mode || payload.r !== revision || !Number.isSafeInteger(payload.o) || (payload.o ?? -1) < 0 || (payload.o ?? 0) > TOOL_SEARCH_CURSOR_OFFSET_MAX) {
     throw new TBError("invalid_argument", "\u641C\u7D22 cursor \u5DF2\u5931\u6548\u6216\u4E0E\u5F53\u524D\u67E5\u8BE2\u4E0D\u5339\u914D");
   }
   return payload.o ?? 0;
 }
+async function encodeToolSearchCursorForCandidate(query, mode, candidate, secret) {
+  const fingerprint = candidate.searchOptionsFingerprint ?? toolSearchOptionsFingerprint();
+  if (!/^[a-f0-9]{16}$/.test(fingerprint)) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22\u5019\u9009\u7684 options fingerprint \u975E\u6CD5");
+  }
+  return await sealToolSearchCursor(
+    query,
+    mode,
+    candidate.revision,
+    candidate.resumeOffset,
+    secret,
+    fingerprint
+  );
+}
 
 // ../core/src/search/sqlSearchIndex.ts
 var TOOL_SEARCH_SCHEMA_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS tb_search_tools_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_tools_v5 (
     id INTEGER PRIMARY KEY,
     path TEXT NOT NULL,
     name TEXT NOT NULL,
     description TEXT NOT NULL DEFAULT '',
+    effect TEXT NOT NULL CHECK (effect IN ('read', 'write', 'destructive', 'unknown')),
     feedback TEXT NOT NULL DEFAULT '',
     UNIQUE(path, name)
   )`,
-  `CREATE TABLE IF NOT EXISTS tb_search_meta_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_meta_v5 (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
     revision INTEGER NOT NULL DEFAULT 0,
     seeded INTEGER NOT NULL DEFAULT 0,
     cursor_secret TEXT NOT NULL
   )`,
-  `INSERT OR IGNORE INTO tb_search_meta_v4(
+  `INSERT OR IGNORE INTO tb_search_meta_v5(
     singleton, revision, seeded, cursor_secret
   ) VALUES (1, 0, 0, lower(hex(randomblob(32))))`,
-  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v5 (
     path TEXT PRIMARY KEY,
     digest TEXT NOT NULL
   )`,
-  `CREATE TRIGGER IF NOT EXISTS tb_search_snapshots_v4_capacity
-  BEFORE INSERT ON tb_search_snapshots_v4
+  `CREATE TRIGGER IF NOT EXISTS tb_search_snapshots_v5_capacity
+  BEFORE INSERT ON tb_search_snapshots_v5
   WHEN NOT EXISTS (
-    SELECT 1 FROM tb_search_snapshots_v4 WHERE path = new.path
-  ) AND (SELECT COUNT(*) FROM tb_search_snapshots_v4) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT}
+    SELECT 1 FROM tb_search_snapshots_v5 WHERE path = new.path
+  ) AND (SELECT COUNT(*) FROM tb_search_snapshots_v5) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT}
   BEGIN
     SELECT RAISE(ABORT, 'tb_search_path_capacity');
   END`
 ];
 var TOOL_SEARCH_CAPACITY_MARKER = "tb_search_path_capacity";
 var TOOL_SEARCH_INSERT_SQL = `
-INSERT INTO tb_search_tools_v4 (path, name, description, feedback)
-VALUES (?, ?, ?, ?)
+INSERT INTO tb_search_tools_v5 (path, name, description, effect, feedback)
+VALUES (?, ?, ?, ?, ?)
 `;
-var TOOL_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v4(path, digest) VALUES (?, ?)";
-var META_SQL = "SELECT revision, seeded, cursor_secret FROM tb_search_meta_v4 WHERE singleton = 1";
-var SNAPSHOT_DIGESTS_SQL = "SELECT path, digest FROM tb_search_snapshots_v4 ORDER BY path";
+var TOOL_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v5(path, digest) VALUES (?, ?)";
+var META_SQL = "SELECT revision, seeded, cursor_secret FROM tb_search_meta_v5 WHERE singleton = 1";
+var SNAPSHOT_DIGESTS_SQL = "SELECT path, digest FROM tb_search_snapshots_v5 ORDER BY path";
 var PATH_STATE_SQL = `
 SELECT snapshots.digest,
-  EXISTS(SELECT 1 FROM tb_search_tools_v4 WHERE path = ?) AS has_tools,
-  (SELECT COUNT(*) FROM tb_search_snapshots_v4) AS path_count
+  EXISTS(SELECT 1 FROM tb_search_tools_v5 WHERE path = ?) AS has_tools,
+  (SELECT COUNT(*) FROM tb_search_snapshots_v5) AS path_count
 FROM (SELECT 1) AS singleton
-LEFT JOIN tb_search_snapshots_v4 AS snapshots ON snapshots.path = ?
+LEFT JOIN tb_search_snapshots_v5 AS snapshots ON snapshots.path = ?
 `;
-var PRESENT_SQL = "SELECT 1 AS present FROM tb_search_tools_v4 WHERE path = ? LIMIT 1";
+var PRESENT_SQL = "SELECT 1 AS present FROM tb_search_tools_v5 WHERE path = ? LIMIT 1";
 var PRESENT_PREFIX_SQL = `
-SELECT 1 AS present FROM tb_search_tools_v4
+SELECT 1 AS present FROM tb_search_tools_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 LIMIT 1
 `;
-var DELETE_TOOLS_SQL = "DELETE FROM tb_search_tools_v4 WHERE path = ?";
-var DELETE_SNAPSHOT_SQL = "DELETE FROM tb_search_snapshots_v4 WHERE path = ?";
+var DELETE_TOOLS_SQL = "DELETE FROM tb_search_tools_v5 WHERE path = ?";
+var DELETE_SNAPSHOT_SQL = "DELETE FROM tb_search_snapshots_v5 WHERE path = ?";
 var DELETE_TOOLS_PREFIX_SQL = `
-DELETE FROM tb_search_tools_v4
+DELETE FROM tb_search_tools_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 `;
 var DELETE_SNAPSHOT_PREFIX_SQL = `
-DELETE FROM tb_search_snapshots_v4
+DELETE FROM tb_search_snapshots_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 `;
-var DELETE_ALL_TOOLS_SQL = "DELETE FROM tb_search_tools_v4";
-var DELETE_ALL_SNAPSHOTS_SQL = "DELETE FROM tb_search_snapshots_v4";
-var BUMP_REVISION_SQL = "UPDATE tb_search_meta_v4 SET revision = revision + 1 WHERE singleton = 1";
-var COMPLETE_REBUILD_SQL = "UPDATE tb_search_meta_v4 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
-function toolSearchCandidateStatement(units, limit, offset, syntax) {
-  const values = units.map((unit, index) => `(${syntax.placeholder(index + 1)}, ${unit.tier})`).join(", ");
-  const limitParam = syntax.placeholder(units.length + 1);
-  const offsetParam = syntax.placeholder(units.length + 2);
+var DELETE_ALL_TOOLS_SQL = "DELETE FROM tb_search_tools_v5";
+var DELETE_ALL_SNAPSHOTS_SQL = "DELETE FROM tb_search_snapshots_v5";
+var BUMP_REVISION_SQL = "UPDATE tb_search_meta_v5 SET revision = revision + 1 WHERE singleton = 1";
+var COMPLETE_REBUILD_SQL = "UPDATE tb_search_meta_v5 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
+function toolSearchEffectSql(effect) {
+  switch (effect) {
+    case "read":
+      return "'read'";
+    case "write":
+      return "'write'";
+    case "destructive":
+      return "'destructive'";
+    case "unknown":
+      return "'unknown'";
+    default:
+      throw new TBError("invalid_argument", `\u5DE5\u5177\u641C\u7D22 effect '${String(effect)}' \u975E\u6CD5`);
+  }
+}
+function toolSearchCandidateStatement(units, totalTermCount, limit, offset, constraints, syntax) {
+  if (!Number.isInteger(totalTermCount) || totalTermCount < 1 || units.some((unit) => !Number.isInteger(unit.logicalTermId) || unit.logicalTermId < 0 || unit.logicalTermId >= totalTermCount)) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 logical term \u8BA1\u5212\u975E\u6CD5");
+  }
+  const values = units.map((unit, index) => `(${unit.logicalTermId}, ${syntax.placeholder(index + 1)}, ${unit.tier}, ${searchUnitAllowsPath(unit) ? 1 : 0})`).join(", ");
+  const hasPrefix = constraints.pathPrefix !== void 0;
+  const prefixParam = hasPrefix ? syntax.placeholder(units.length + 1) : void 0;
+  const trailingStart = units.length + (hasPrefix ? 2 : 1);
+  const limitParam = syntax.placeholder(trailingStart);
+  const offsetParam = syntax.placeholder(trailingStart + 1);
+  const requiredMatchedTerms = constraints.minCoverage === void 0 ? 1 : Math.ceil(constraints.minCoverage * totalTermCount);
   const like = syntax.likeOperator;
+  const effectLiterals = constraints.effects?.map(toolSearchEffectSql);
+  const prefixCte = hasPrefix ? `, prefix_filter(value) AS (VALUES (${prefixParam}))` : "";
+  const filterPredicates = [
+    ...hasPrefix ? [
+      `(
+            tools.path = prefix_filter.value
+            OR substr(tools.path, 1, length(prefix_filter.value) + 1)
+              = prefix_filter.value || '/'
+          )`
+    ] : [],
+    ...effectLiterals === void 0 ? [] : [`tools.effect IN (${effectLiterals.join(", ")})`]
+  ];
+  const filteredToolsCte = filterPredicates.length > 0 ? `,
+      filtered_tools AS (
+        SELECT tools.*
+        FROM tb_search_tools_v5 AS tools
+        ${hasPrefix ? "CROSS JOIN prefix_filter" : ""}
+        WHERE ${filterPredicates.join("\n          AND ")}
+      )` : "";
+  const candidateTable = filterPredicates.length > 0 ? "filtered_tools" : "tb_search_tools_v5";
   return {
-    params: [...units.map((unit) => unit.pattern), limit + 1, offset],
+    params: [
+      ...units.map((unit) => unit.pattern),
+      ...hasPrefix ? [constraints.pathPrefix] : [],
+      limit + 1,
+      offset
+    ],
     sql: `
-      WITH units(pattern, tier) AS (VALUES ${values})
-      SELECT * FROM (
-        SELECT tools.id, tools.path, tools.name,
-          (
-            SELECT COALESCE(SUM(units.tier * CASE
-              WHEN tools.name ${like} units.pattern ESCAPE '!' THEN 10
-              WHEN tools.path ${like} units.pattern ESCAPE '!' THEN 5
-              WHEN tools.description ${like} units.pattern ESCAPE '!' THEN 3
-              WHEN tools.feedback ${like} units.pattern ESCAPE '!' THEN 1
-              ELSE 0
-            END), 0)
-            FROM units
-          ) AS score
-        FROM tb_search_tools_v4 AS tools
-      ) AS scored_tools
-      WHERE score > 0
-      ORDER BY score DESC, path, name
+      WITH units(logical_term_id, pattern, tier, path_allowed) AS (VALUES ${values})${prefixCte}${filteredToolsCte},
+      unit_matches AS (
+        SELECT tools.id, tools.path, tools.name, units.logical_term_id,
+          units.tier * CASE
+            WHEN tools.name ${like} units.pattern ESCAPE '!' THEN 10
+            WHEN units.path_allowed = 1
+              AND tools.path ${like} units.pattern ESCAPE '!' THEN 5
+            WHEN tools.description ${like} units.pattern ESCAPE '!' THEN 3
+            WHEN tools.feedback ${like} units.pattern ESCAPE '!' THEN 1
+            ELSE 0
+          END AS unit_score
+        FROM ${candidateTable} AS tools
+        CROSS JOIN units
+      ),
+      term_matches AS (
+        SELECT id, path, name, logical_term_id, MAX(unit_score) AS term_score
+        FROM unit_matches
+        WHERE unit_score > 0
+        GROUP BY id, path, name, logical_term_id
+      ),
+      scored_tools AS (
+        SELECT id, path, name,
+          CAST(COUNT(*) AS INTEGER) AS matched_term_count,
+          CAST(SUM(term_score) AS INTEGER) AS score
+        FROM term_matches
+        GROUP BY id, path, name
+      )
+      SELECT id, path, name, matched_term_count, ${totalTermCount} AS total_term_count
+      FROM scored_tools
+      WHERE matched_term_count >= ${requiredMatchedTerms}
+      ORDER BY matched_term_count DESC, score DESC, path, name
       LIMIT ${limitParam} OFFSET ${offsetParam}
     `
   };
 }
 var sqliteSearchDialect = {
-  candidateStatement: (query, limit, offset) => toolSearchCandidateStatement(
-    prepareToolSearchUnits(query),
-    limit,
-    offset,
-    { likeOperator: "LIKE", placeholder: () => "?" }
-  ),
+  candidateStatement: (query, limit, offset, rawConstraints) => {
+    const constraints = normalizeToolSearchOptions(rawConstraints);
+    const prepared = prepareToolSearchQuery(
+      query,
+      constraints.pathPrefix === void 0 ? TOOL_SEARCH_UNIT_LIMIT : TOOL_SEARCH_UNIT_LIMIT - 1
+    );
+    return toolSearchCandidateStatement(
+      prepared.units,
+      prepared.totalTermCount,
+      limit,
+      offset,
+      constraints,
+      { likeOperator: "LIKE", placeholder: () => "?" }
+    );
+  },
   schemaStatements: TOOL_SEARCH_SCHEMA_STATEMENTS,
   statements: {
     bumpRevision: BUMP_REVISION_SQL,
@@ -20555,6 +21596,10 @@ var SqlSearchIndex = class {
     await this.driver.ensureSchema();
     return (await this.meta()).seeded === 1;
   }
+  async revision() {
+    await this.driver.ensureSchema();
+    return (await this.meta()).revision;
+  }
   async replace(path, tools, opts = {}) {
     const canonical = normalizeToolSearchPath(path);
     const records = serializeToolSearchSnapshot(canonical, tools, opts.feedback ?? "");
@@ -20633,6 +21678,8 @@ var SqlSearchIndex = class {
   async search(query, opts) {
     assertKeywordToolSearchMode(opts);
     const normalized = normalizeToolSearchQuery(query);
+    const constraints = normalizeToolSearchOptions(opts);
+    const optionsFingerprint = toolSearchOptionsFingerprint(constraints);
     const mode = opts?.mode ?? "keyword";
     await this.driver.ensureSchema();
     const meta3 = await this.meta();
@@ -20642,20 +21689,28 @@ var SqlSearchIndex = class {
       normalized,
       mode,
       revision,
-      meta3.cursor_secret
+      meta3.cursor_secret,
+      constraints
     );
     const limit = Math.min(normalizeToolSearchLimit(opts?.limit), TOOL_SEARCH_BATCH_LIMIT);
     const rows = await this.driver.all(
-      this.dialect.candidateStatement(normalized, limit, offset)
+      this.dialect.candidateStatement(normalized, limit, offset, constraints)
     );
-    const hasMore = rows.length > limit;
-    const page = hasMore ? rows.slice(0, limit) : rows;
+    const firstBand = rows[0]?.matched_term_count;
+    const bandEnd = constraints.matching === "best" && firstBand !== void 0 ? rows.findIndex((row) => row.matched_term_count !== firstBand) : -1;
+    const pageLength = bandEnd >= 0 ? Math.min(limit, bandEnd) : Math.min(limit, rows.length);
+    const page = rows.slice(0, pageLength);
+    const hasMore = rows.length > page.length;
     const items = page.map((row, index) => ({
+      coverage: row.matched_term_count / row.total_term_count,
+      matchedTermCount: row.matched_term_count,
       name: row.name,
       path: row.path,
       ref: String(row.id),
       resumeOffset: offset + index + 1,
-      revision
+      revision,
+      searchOptionsFingerprint: optionsFingerprint,
+      totalTermCount: row.total_term_count
     }));
     const last = items[items.length - 1];
     return hasMore && last !== void 0 ? {
@@ -20665,7 +21720,8 @@ var SqlSearchIndex = class {
         mode,
         revision,
         last.resumeOffset,
-        meta3.cursor_secret
+        meta3.cursor_secret,
+        constraints
       )
     } : { items };
   }
@@ -20675,11 +21731,10 @@ var SqlSearchIndex = class {
     if (candidate.revision !== meta3.revision) {
       throw new TBError("invalid_argument", "\u641C\u7D22 cursor \u5DF2\u5931\u6548");
     }
-    return await encodeToolSearchCursor(
+    return await encodeToolSearchCursorForCandidate(
       query,
       mode,
-      meta3.revision,
-      candidate.resumeOffset,
+      candidate,
       meta3.cursor_secret
     );
   }
@@ -20687,11 +21742,12 @@ var SqlSearchIndex = class {
 
 // ../core/src/search/pgSearchDialect.ts
 var PG_SEARCH_SCHEMA_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS tb_search_tools_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_tools_v5 (
     id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
     path text NOT NULL,
     name text NOT NULL,
     description text NOT NULL DEFAULT '',
+    effect text NOT NULL CHECK (effect IN ('read', 'write', 'destructive', 'unknown')),
     feedback text NOT NULL DEFAULT '',
     UNIQUE(path, name)
   )`,
@@ -20699,7 +21755,7 @@ var PG_SEARCH_SCHEMA_STATEMENTS = [
   // 样本上对单 unit 多列 ILIKE 一律选 Seq Scan；GIN 让写入和体积显著增加却未改善
   // 检索。4000 行只是代表样本，不是严格工具行上限（节点内还受 20KB JSON 约束）；
   // 查询单元数或容量边界变化时，应重跑 searchBench 并重新评估查询形状与索引。
-  `CREATE TABLE IF NOT EXISTS tb_search_meta_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_meta_v5 (
     singleton integer PRIMARY KEY CHECK (singleton = 1),
     revision bigint NOT NULL DEFAULT 0,
     seeded integer NOT NULL DEFAULT 0,
@@ -20707,32 +21763,32 @@ var PG_SEARCH_SCHEMA_STATEMENTS = [
   )`,
   // cursor_secret 需 64 hex(32 字节)。两个内置 gen_random_uuid() 去连字符正好 64
   // hex,避免依赖 pgcrypto 的 gen_random_bytes(自托管 PG 未必预装 pgcrypto)。
-  `INSERT INTO tb_search_meta_v4(singleton, revision, seeded, cursor_secret)
+  `INSERT INTO tb_search_meta_v5(singleton, revision, seeded, cursor_secret)
     VALUES (
       1, 0, 0,
       replace(gen_random_uuid()::text, '-', '') || replace(gen_random_uuid()::text, '-', '')
     )
     ON CONFLICT (singleton) DO NOTHING`,
-  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v5 (
     path text PRIMARY KEY,
     digest text NOT NULL
   )`,
-  `CREATE OR REPLACE FUNCTION tb_search_snapshots_v4_capacity()
+  `CREATE OR REPLACE FUNCTION tb_search_snapshots_v5_capacity()
     RETURNS trigger AS $$
     BEGIN
-      IF (SELECT COUNT(*) FROM tb_search_snapshots_v4) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT} THEN
+      IF (SELECT COUNT(*) FROM tb_search_snapshots_v5) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT} THEN
         RAISE EXCEPTION '${TOOL_SEARCH_CAPACITY_MARKER}';
       END IF;
       RETURN NEW;
     END;
     $$ LANGUAGE plpgsql`,
-  `DROP TRIGGER IF EXISTS tb_search_snapshots_v4_capacity_trg ON tb_search_snapshots_v4`,
-  `CREATE TRIGGER tb_search_snapshots_v4_capacity_trg
-    BEFORE INSERT ON tb_search_snapshots_v4
-    FOR EACH ROW EXECUTE FUNCTION tb_search_snapshots_v4_capacity()`
+  `DROP TRIGGER IF EXISTS tb_search_snapshots_v5_capacity_trg ON tb_search_snapshots_v5`,
+  `CREATE TRIGGER tb_search_snapshots_v5_capacity_trg
+    BEFORE INSERT ON tb_search_snapshots_v5
+    FOR EACH ROW EXECUTE FUNCTION tb_search_snapshots_v5_capacity()`
 ];
 var PG_SEARCH_WRITE_LOCK_KEY = 2069799624;
-var PG_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v4(path, digest) VALUES ($1, $2)";
+var PG_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v5(path, digest) VALUES ($1, $2)";
 function pgBulkInsertSql(table, columns, rows) {
   const tuples = [];
   for (let r = 0; r < rows; r++) {
@@ -20741,50 +21797,65 @@ function pgBulkInsertSql(table, columns, rows) {
   }
   return `INSERT INTO ${table} (${columns.join(", ")}) VALUES ${tuples.join(", ")}`;
 }
-var PG_SEARCH_TOOLS_TABLE = "tb_search_tools_v4";
-var PG_SEARCH_TOOLS_COLUMNS = ["path", "name", "description", "feedback"];
-var PG_SEARCH_SNAPSHOTS_TABLE = "tb_search_snapshots_v4";
+var PG_SEARCH_TOOLS_TABLE = "tb_search_tools_v5";
+var PG_SEARCH_TOOLS_COLUMNS = [
+  "path",
+  "name",
+  "description",
+  "effect",
+  "feedback"
+];
+var PG_SEARCH_SNAPSHOTS_TABLE = "tb_search_snapshots_v5";
 var PG_SEARCH_SNAPSHOTS_COLUMNS = ["path", "digest"];
 var PG_SEARCH_INSERT_ROWS_MAX = 1e3;
 var META_SQL2 = `
 SELECT revision::int AS revision, seeded::int AS seeded, cursor_secret
-FROM tb_search_meta_v4 WHERE singleton = 1
+FROM tb_search_meta_v5 WHERE singleton = 1
 `;
-var SNAPSHOT_DIGESTS_SQL2 = "SELECT path, digest FROM tb_search_snapshots_v4 ORDER BY path";
+var SNAPSHOT_DIGESTS_SQL2 = "SELECT path, digest FROM tb_search_snapshots_v5 ORDER BY path";
 var PATH_STATE_SQL2 = `
 SELECT snapshots.digest,
-  EXISTS(SELECT 1 FROM tb_search_tools_v4 WHERE path = $1)::int AS has_tools,
-  (SELECT COUNT(*) FROM tb_search_snapshots_v4)::int AS path_count
+  EXISTS(SELECT 1 FROM tb_search_tools_v5 WHERE path = $1)::int AS has_tools,
+  (SELECT COUNT(*) FROM tb_search_snapshots_v5)::int AS path_count
 FROM (SELECT 1) AS singleton
-LEFT JOIN tb_search_snapshots_v4 AS snapshots ON snapshots.path = $2
+LEFT JOIN tb_search_snapshots_v5 AS snapshots ON snapshots.path = $2
 `;
-var PRESENT_SQL2 = "SELECT 1 AS present FROM tb_search_tools_v4 WHERE path = $1 LIMIT 1";
+var PRESENT_SQL2 = "SELECT 1 AS present FROM tb_search_tools_v5 WHERE path = $1 LIMIT 1";
 var PRESENT_PREFIX_SQL2 = `
-SELECT 1 AS present FROM tb_search_tools_v4
+SELECT 1 AS present FROM tb_search_tools_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 LIMIT 1
 `;
-var DELETE_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v4 WHERE path = $1";
-var DELETE_SNAPSHOT_SQL2 = "DELETE FROM tb_search_snapshots_v4 WHERE path = $1";
+var DELETE_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v5 WHERE path = $1";
+var DELETE_SNAPSHOT_SQL2 = "DELETE FROM tb_search_snapshots_v5 WHERE path = $1";
 var DELETE_TOOLS_PREFIX_SQL2 = `
-DELETE FROM tb_search_tools_v4
+DELETE FROM tb_search_tools_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 `;
 var DELETE_SNAPSHOT_PREFIX_SQL2 = `
-DELETE FROM tb_search_snapshots_v4
+DELETE FROM tb_search_snapshots_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 `;
-var DELETE_ALL_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v4";
-var DELETE_ALL_SNAPSHOTS_SQL2 = "DELETE FROM tb_search_snapshots_v4";
-var BUMP_REVISION_SQL2 = "UPDATE tb_search_meta_v4 SET revision = revision + 1 WHERE singleton = 1";
-var COMPLETE_REBUILD_SQL2 = "UPDATE tb_search_meta_v4 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
+var DELETE_ALL_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v5";
+var DELETE_ALL_SNAPSHOTS_SQL2 = "DELETE FROM tb_search_snapshots_v5";
+var BUMP_REVISION_SQL2 = "UPDATE tb_search_meta_v5 SET revision = revision + 1 WHERE singleton = 1";
+var COMPLETE_REBUILD_SQL2 = "UPDATE tb_search_meta_v5 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
 var pgSearchDialect = {
-  candidateStatement: (query, limit, offset) => toolSearchCandidateStatement(
-    prepareToolSearchUnits(query),
-    limit,
-    offset,
-    { likeOperator: "ILIKE", placeholder: (index) => `$${index}` }
-  ),
+  candidateStatement: (query, limit, offset, rawConstraints) => {
+    const constraints = normalizeToolSearchOptions(rawConstraints);
+    const prepared = prepareToolSearchQuery(
+      query,
+      constraints.pathPrefix === void 0 ? TOOL_SEARCH_UNIT_LIMIT : TOOL_SEARCH_UNIT_LIMIT - 1
+    );
+    return toolSearchCandidateStatement(
+      prepared.units,
+      prepared.totalTermCount,
+      limit,
+      offset,
+      constraints,
+      { likeOperator: "ILIKE", placeholder: (index) => `$${index}` }
+    );
+  },
   schemaStatements: PG_SEARCH_SCHEMA_STATEMENTS,
   statements: {
     bumpRevision: BUMP_REVISION_SQL2,
@@ -21098,7 +22169,7 @@ function guessContentType(path) {
   if (dot < 0) return "text/plain";
   return CONTENT_TYPE_BY_EXT[path.slice(dot + 1).toLowerCase()] ?? "text/plain";
 }
-function clampLimit4(limit) {
+function clampLimit5(limit) {
   if (limit === void 0) return LIST_LIMIT_DEFAULT;
   if (!Number.isInteger(limit) || limit < 1) {
     throw new TBError("invalid_argument", `limit \u975E\u6CD5:${limit}`);
@@ -21153,7 +22224,7 @@ function createSkillhubProvider(store, opts) {
   };
   return {
     async list(listOpts) {
-      const limit = clampLimit4(listOpts?.limit);
+      const limit = clampLimit5(listOpts?.limit);
       const res = await store.list(keyPrefix, {
         delimiter: "/",
         cursor: listOpts?.cursor,
@@ -21213,7 +22284,7 @@ function createSkillhubProvider(store, opts) {
       if (typeof query !== "string" || query === "") {
         throw new TBError("invalid_argument", "query \u4E0D\u80FD\u4E3A\u7A7A");
       }
-      const limit = clampLimit4(searchOpts?.limit);
+      const limit = clampLimit5(searchOpts?.limit);
       const q = query.toLowerCase();
       const after = searchOpts?.cursor;
       const items = [];
@@ -21388,6 +22459,7 @@ function toolToCmd(nodePath, tool, index) {
   if (tool.description !== void 0) {
     cmd.h = index ? summarizeOneLine(tool.description) : tool.description;
   }
+  if (tool.delivery !== void 0) cmd.delivery = tool.delivery;
   if (!index && tool.inputSchema !== void 0) cmd.inputSchema = tool.inputSchema;
   if (!index && tool.outputSchema !== void 0) cmd.outputSchema = tool.outputSchema;
   if (tool.effect !== void 0) cmd.effect = tool.effect;
@@ -21494,7 +22566,15 @@ function virtualizeTools(v, upstream) {
   const hidden = new Set(v?.hide ?? []);
   for (const tool of upstream) {
     if (hidden.has(tool.name)) continue;
-    const name = v ? virtualName(v, tool.name) : tool.name;
+    const projectedName = v ? virtualName(v, tool.name) : tool.name;
+    const name = canonicalizeSegment(projectedName);
+    const previous = reverse.get(name);
+    if (previous !== void 0) {
+      throw new TBError(
+        "invalid_argument",
+        `\u5DE5\u5177\u540D '${previous}' \u4E0E '${tool.name}' \u89C4\u8303\u5316\u540E\u51B2\u7A81:'${name}',\u8BF7\u663E\u5F0F rename`
+      );
+    }
     const description = v?.describe?.[tool.name] ?? tool.description;
     exposed.push({ ...tool, name, description });
     reverse.set(name, tool.name);
@@ -21511,7 +22591,7 @@ function resolveUpstreamTool(v, source, virtualName2) {
 }
 
 // ../core/src/tree/registry.ts
-function clampLimit5(limit) {
+function clampLimit6(limit) {
   if (limit === void 0 || limit < 1) return LIST_LIMIT_DEFAULT;
   return limit > LIST_LIMIT_MAX ? LIST_LIMIT_MAX : limit;
 }
@@ -21612,7 +22692,7 @@ var NodeRegistryStore = class {
    */
   async list(prefix, opts) {
     const normPrefix = prefix === void 0 ? "" : canonicalizePath(prefix);
-    const limit = clampLimit5(opts?.limit);
+    const limit = clampLimit6(opts?.limit);
     const all = (await this.scanAll()).filter((n) => isPrefixOf(normPrefix, n.path)).sort(byPath);
     const cursor = opts?.cursor;
     const start = cursor ? all.findIndex((n) => n.path === cursor) + 1 : 0;
@@ -21701,6 +22781,7 @@ var NodeRegistryStore = class {
       description: node.description,
       ...node.config !== void 0 ? { config: node.config } : {},
       ...node.virtualize !== void 0 ? { virtualize: node.virtualize } : {},
+      ...opts.deviceId !== void 0 ? { deviceId: opts.deviceId } : {},
       ...opts.online !== void 0 ? { online: opts.online } : {},
       ...opts.lastSeenAt !== void 0 ? { lastSeenAt: opts.lastSeenAt } : {},
       registeredBy,
@@ -21921,8 +23002,8 @@ function createPlugin(opts = {}) {
     const b64 = raw.replaceAll("-", "+").replaceAll("_", "/");
     const padded = b64.padEnd(b64.length + (4 - b64.length % 4) % 4, "=");
     try {
-      const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
-      return new TextDecoder().decode(bytes);
+      const bytes2 = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+      return new TextDecoder().decode(bytes2);
     } catch {
       throw new TBError("invalid_argument", `${HEADER_TB_UPSTREAM_AUTH} is not valid base64url`);
     }
@@ -22248,12 +23329,26 @@ export {
   pluginTokenSecretName,
   createStoreModule,
   RemoteAllowlistStore,
+  DeviceMailboxService,
   tbErrorBodySchema,
   nodeInputSchema,
   helpJsonSchema,
   treeJsonSchema,
+  toolSearchRelevanceSchema,
+  toolSearchSourceSchema,
+  toolSearchSourceResultSchema,
   toolSearchPageSchema,
   toolSearchRequestSchema,
+  deviceOperationSummarySchema,
+  deviceOperationDetailSchema,
+  deviceOperationListRequestSchema,
+  deviceOperationListResponseSchema,
+  deviceOperationIdentityRequestSchema,
+  deviceOperationClaimRequestSchema,
+  deviceOperationClaimResponseSchema,
+  deviceOperationRenewRequestSchema,
+  deviceOperationRenewResponseSchema,
+  deviceOperationCompleteRequestSchema,
   registryNodeSchema,
   feedbackViewSchema,
   feedbackDetailSchema,
@@ -22320,11 +23415,15 @@ export {
   TOOL_SEARCH_BATCH_LIMIT,
   TOOL_SEARCH_WORK_LIMIT,
   TOOL_SEARCH_AUDIT_NODE_LIMIT,
+  TOOL_SEARCH_DESCRIPTION_BYTES_MAX,
   TOOL_SEARCH_PAGE_BYTES,
+  TOOL_SEARCH_RANKING_VERSION,
   normalizeToolSearchLimit,
   normalizeToolSearchPath,
+  normalizeToolSearchOptions,
   serializeToolSearchSnapshot,
   toolSearchSnapshotDigest,
+  prepareToolSearchQuery,
   TOOL_SEARCH_SCHEMA_STATEMENTS,
   TOOL_SEARCH_INSERT_SQL,
   TOOL_SEARCH_INSERT_SNAPSHOT_SQL,