@tool-bridge/server 0.10.0 → 0.12.0

package/dist/{chunk-Q7YHZ2SD.js → chunk-TXOHC56J.js}

@@ -115,6 +115,7 @@ import {
   pgBulkInsertSql,
   pgSearchDialect,
   pluginTokenSecretName,
+  prefixUpperBound,
   preprocess,
   record,
   renderHelpDsl,
@@ -140,7 +141,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-TPGTA43F.js";
+} from "./chunk-4U5OQW7F.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -19102,16 +19103,16 @@ function createMcpProvider(config, secrets, opts) {
 function createPluginToolProvider(opts) {
   return {
     list: async () => {
-      const value = await callPlugin(opts, "List", {});
+      const value = await callPlugin(opts, "list", {});
       if (!Array.isArray(value)) {
-        throw new TBError("unavailable", `plugin '${opts.manifest.id}' \u7684 List \u672A\u8FD4\u56DE\u5DE5\u5177\u6570\u7EC4`, {
+        throw new TBError("unavailable", `plugin '${opts.manifest.id}' \u7684 list \u672A\u8FD4\u56DE\u5DE5\u5177\u6570\u7EC4`, {
           retryable: false
         });
       }
       return value;
     },
     call: async (name, args) => {
-      const value = await callPlugin(opts, "Call", { name, args });
+      const value = await callPlugin(opts, "call", { name, args });
       if (value !== null && typeof value === "object" && "content" in value) {
         return value;
       }
@@ -19737,23 +19738,23 @@ async function skillhubProviderFor(node, cfg, deps, requestUrl) {
   return createSkillhubProvider(objects, opts);
 }
 async function dispatchSkillhubCmd(provider, tool, args) {
-  switch (tool) {
-    case "List":
-      return await provider.List(args.opts);
-    case "Get":
-      return typeof args.file === "string" ? await provider.GetFile(args.id, args.file) : await provider.Get(args.id);
-    case "Search":
-      return await provider.Search(args.query, args.opts);
-    case "Publish":
+  switch (tool.toLowerCase()) {
+    case "list":
+      return await provider.list(args.opts);
+    case "get":
+      return typeof args.file === "string" ? await provider.get_file(args.id, args.file) : await provider.get(args.id);
+    case "search":
+      return await provider.search(args.query, args.opts);
+    case "publish":
       if (!Array.isArray(args.files)) {
-        throw new TBError("invalid_argument", "Publish \u9700\u8981\u6570\u7EC4 'files'");
+        throw new TBError("invalid_argument", "publish \u9700\u8981\u6570\u7EC4 'files'");
       }
-      return await provider.Publish({
+      return await provider.publish({
         ...typeof args.id === "string" ? { id: args.id } : {},
         files: args.files
       });
-    case "Remove":
-      return await provider.Remove(args.id);
+    case "remove":
+      return await provider.remove(args.id);
     default:
       throw new TBError("invalid_argument", `unknown cmd '${tool}'`);
   }
@@ -19762,31 +19763,31 @@ async function dispatchContextCmd(provider, tool, args) {
   const unimplemented = () => {
     throw new TBError("invalid_argument", `unknown cmd '${tool}'(provider \u672A\u5B9E\u73B0)`);
   };
-  switch (tool) {
-    case "List":
-      if (provider.List === void 0) return unimplemented();
-      return await provider.List(args.path ?? "", args.opts);
-    case "Get":
-      if (provider.Get === void 0) return unimplemented();
-      return await provider.Get(args.path);
-    case "Write":
-      if (provider.Write === void 0) return unimplemented();
+  switch (tool.toLowerCase()) {
+    case "list":
+      if (provider.list === void 0) return unimplemented();
+      return await provider.list(args.path ?? "", args.opts);
+    case "get":
+      if (provider.get === void 0) return unimplemented();
+      return await provider.get(args.path);
+    case "write":
+      if (provider.write === void 0) return unimplemented();
       if (typeof args.entry !== "object" || args.entry === null) {
-        throw new TBError("invalid_argument", "Write \u9700\u8981\u5BF9\u8C61 'entry'");
+        throw new TBError("invalid_argument", "write \u9700\u8981\u5BF9\u8C61 'entry'");
       }
-      return await provider.Write(args.path, args.entry);
-    case "Update":
-      if (provider.Update === void 0) return unimplemented();
+      return await provider.write(args.path, args.entry);
+    case "update":
+      if (provider.update === void 0) return unimplemented();
       if (typeof args.patch !== "object" || args.patch === null) {
-        throw new TBError("invalid_argument", "Update \u9700\u8981\u5BF9\u8C61 'patch'");
-      }
-      return await provider.Update(args.path, args.patch);
-    case "Delete":
-      if (provider.Delete === void 0) return unimplemented();
-      return await provider.Delete(args.path);
-    case "Search":
-      if (provider.Search === void 0) return unimplemented();
-      return await provider.Search(args.query, args.opts);
+        throw new TBError("invalid_argument", "update \u9700\u8981\u5BF9\u8C61 'patch'");
+      }
+      return await provider.update(args.path, args.patch);
+    case "delete":
+      if (provider.delete === void 0) return unimplemented();
+      return await provider.delete(args.path);
+    case "search":
+      if (provider.search === void 0) return unimplemented();
+      return await provider.search(args.query, args.opts);
     default:
       throw new TBError("invalid_argument", `unknown cmd '${tool}'`);
   }
@@ -35582,8 +35583,8 @@ var CfWorkerJsonSchemaValidator2 = class {
 function hex(bytes) {
   return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-function mcpToolIdentity(invokePath, toolName, invokeWithEnvelope) {
-  return JSON.stringify([invokePath, toolName, invokeWithEnvelope ? "envelope" : "flat"]);
+function mcpToolIdentity(invokePath, toolName) {
+  return JSON.stringify([invokePath, toolName]);
 }
 async function mcpToolName(identity) {
   const encoded = [...new TextEncoder().encode(identity)].map((byte) => {
@@ -35793,33 +35794,33 @@ async function handleMcpRequest(request, version, bridge, listTtlMs) {
 }
 
 // ../app/src/providers/pluginContext.ts
-var CORE_METHODS = ["List", "Get", "Write", "Update"];
+var CORE_METHODS = ["list", "get", "write", "update"];
 function createPluginContextProvider(opts) {
   const call = (method, args) => callPlugin(opts, method, args);
   const declared = opts.methods !== void 0 ? new Set(opts.methods) : /* @__PURE__ */ new Set([...CORE_METHODS, ...optionalMethodsForCapabilities(opts.capabilities)]);
   const provider = {};
-  if (declared.has("List")) {
-    provider.List = (path, listOpts) => call("List", { path, ...listOpts !== void 0 ? { opts: listOpts } : {} });
+  if (declared.has("list")) {
+    provider.list = (path, listOpts) => call("list", { path, ...listOpts !== void 0 ? { opts: listOpts } : {} });
   }
-  if (declared.has("Get")) {
-    provider.Get = (path) => call("Get", { path });
+  if (declared.has("get")) {
+    provider.get = (path) => call("get", { path });
   }
-  if (declared.has("Update")) {
-    provider.Update = (path, patch) => call("Update", { path, patch });
+  if (declared.has("update")) {
+    provider.update = (path, patch) => call("update", { path, patch });
   }
-  if (declared.has("Write")) {
-    provider.Write = (path, entry) => call("Write", { path, entry });
+  if (declared.has("write")) {
+    provider.write = (path, entry) => call("write", { path, entry });
   }
   const optional2 = optionalMethodsForCapabilities(opts.capabilities);
-  if (declared.has("Search") && optional2.has("Search")) {
-    provider.Search = (query, searchOpts) => call("Search", {
+  if (declared.has("search") && optional2.has("search")) {
+    provider.search = (query, searchOpts) => call("search", {
       query,
       ...searchOpts !== void 0 ? { opts: searchOpts } : {}
     });
   }
-  if (declared.has("Delete") && optional2.has("Delete")) {
-    provider.Delete = async (path) => {
-      await call("Delete", { path });
+  if (declared.has("delete") && optional2.has("delete")) {
+    provider.delete = async (path) => {
+      await call("delete", { path });
     };
   }
   return provider;
@@ -36578,10 +36579,15 @@ function registerPublicRoutes(app, env) {
       return tbErrorResponse(TBError.notFound("dashboard assets not deployed"));
     }
     const url2 = new URL(c.req.url);
+    const fwd = new Headers();
+    const ae = c.req.header("accept-encoding");
+    if (ae) fwd.set("accept-encoding", ae);
+    const inm = c.req.header("if-none-match");
+    if (inm) fwd.set("if-none-match", inm);
     const sub = url2.pathname.slice("/ui".length) || "/";
-    const res = await assets(new Request(new URL(sub, url2.origin)));
+    const res = await assets(new Request(new URL(sub, url2.origin), { headers: fwd }));
     if (res.status !== 404) return res;
-    return await assets(new Request(new URL("/", url2.origin)));
+    return await assets(new Request(new URL("/", url2.origin), { headers: fwd }));
   };
   app.get("/ui", (c) => c.redirect("/ui/", 302));
   app.get("/ui/*", serveUi);
@@ -36860,10 +36866,10 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
         node.config.export
       );
       const declared = exported.methods !== void 0 ? new Set(exported.methods) : /* @__PURE__ */ new Set([
-        "List",
-        "Get",
-        "Write",
-        "Update",
+        "list",
+        "get",
+        "write",
+        "update",
         ...optionalMethodsForCapabilities(exported.capabilities ?? [])
       ]);
       return { ...model, cmds: model.cmds.filter((c) => declared.has(c.name)) };
@@ -36876,23 +36882,40 @@ async function helpModelFor(node, registry, ctx, builtins, deps, opts) {
   }
   throw TBError.unimplemented(`~help for kind '${node.kind}' not implemented yet`);
 }
+async function commandHelpModelFor(registry, ctx, builtins, deps, path, opts) {
+  const resolved = await registry.resolve(path).catch(() => null);
+  if (resolved === null || resolved.rest === "" || resolved.rest.includes("/")) return null;
+  const { node, rest: command } = resolved;
+  if (!(node.kind === "builtin" || node.kind === "context" || node.kind === "skillhub")) {
+    return null;
+  }
+  const full = await helpModelFor(node, registry, ctx, builtins, deps, {
+    refresh: opts.refresh,
+    schemas: true,
+    now: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const cmd = full.cmds.find((c) => c.name === command);
+  if (cmd === void 0) return null;
+  return {
+    node: { path: `${node.path}/${command}`, kind: node.kind, description: cmd.h ?? full.node.description },
+    cmds: [cmd]
+  };
+}
 
 // ../app/src/routes/mcp.ts
 var MCP_REMOTE_MAX_REQUESTS = 32;
 var mcpCommand = (nodePath, nodeDescription, command) => {
   const modelPath = nodePath.replace(/^\/+|\/+$/g, "");
   const commandPath = command.path.replace(/^\/+|\/+$/g, "");
-  if (commandPath !== modelPath && !commandPath.startsWith(`${modelPath}/`)) {
+  if (!commandPath.startsWith(`${modelPath}/`)) {
     throw new TBError("internal", `command path '${command.path}' escapes node '${nodePath}'`);
   }
   const invokePath = `/${commandPath}`;
-  const invokeWithEnvelope = commandPath === modelPath;
   return {
-    identity: mcpToolIdentity(invokePath, command.name, invokeWithEnvelope),
+    identity: mcpToolIdentity(invokePath, command.name),
     sourcePath: nodePath,
     toolName: command.name,
     invokePath,
-    invokeWithEnvelope,
     description: command.h ?? nodeDescription,
     ...command.inputSchema !== void 0 ? { inputSchema: command.inputSchema } : {},
     ...command.effect !== void 0 ? { effect: command.effect } : {},
@@ -36900,13 +36923,12 @@ var mcpCommand = (nodePath, nodeDescription, command) => {
   };
 };
 var toolSpecCommand = (node, tool, providerBacked = false) => {
-  const path = `/${node.path}`;
+  const invokePath = `/${node.path}/${tool.name}`;
   return {
-    identity: mcpToolIdentity(path, tool.name, true),
+    identity: mcpToolIdentity(invokePath, tool.name),
     sourcePath: node.path,
     toolName: tool.name,
-    invokePath: path,
-    invokeWithEnvelope: true,
+    invokePath,
     ...providerBacked ? { providerBacked: true } : {},
     description: tool.description ?? node.description,
     ...tool.inputSchema !== void 0 ? { inputSchema: tool.inputSchema } : {},
@@ -36921,12 +36943,9 @@ var remoteCommand = (localNodePath, model, command) => {
     throw new TBError("unavailable", "remote ~help returned a command outside its node");
   }
   const suffix = remoteCommandPath.slice(remoteNodePath.length);
-  const directTool = suffix.startsWith("/");
   return mcpCommand(localNodePath, model.node.description, {
     ...command,
-    // Tool-layer nodes retain the envelope entrypoint. It keeps authorization on the
-    // node path instead of requiring callers to hold an exact scope for the tool suffix.
-    path: directTool ? `/${localNodePath}` : `/${localNodePath}${suffix}`
+    path: `/${localNodePath}${suffix}`
   });
 };
 function mcpBridgeFor(c, env, app) {
@@ -36940,7 +36959,6 @@ function mcpBridgeFor(c, env, app) {
       sourcePath: "",
       toolName: "Search",
       invokePath: "/~search",
-      invokeWithEnvelope: false,
       mcpName: "tb_search",
       operation: "search",
       description: "Search visible tools across the Tool Bridge tree.",
@@ -36962,7 +36980,6 @@ function mcpBridgeFor(c, env, app) {
       sourcePath: "",
       toolName: "Help",
       invokePath: "/~help",
-      invokeWithEnvelope: false,
       mcpName: "tb_help",
       operation: "help",
       description: "Describe a visible Tool Bridge node or one of its tools.",
@@ -36982,7 +36999,6 @@ function mcpBridgeFor(c, env, app) {
       sourcePath: "",
       toolName: "List",
       invokePath: "/~tree",
-      invokeWithEnvelope: false,
       mcpName: "tb_list_nodes",
       operation: "listNodes",
       description: "List the visible Tool Bridge node tree from a path.",
@@ -37226,9 +37242,8 @@ function mcpBridgeFor(c, env, app) {
         "authorization": c.req.header("authorization") ?? "",
         "content-type": "application/json"
       });
-      const body = tool.invokeWithEnvelope ? { tool: tool.toolName, arguments: args } : args;
       const response = await app.request(
-        new Request(url2, { method: "POST", headers, body: JSON.stringify(body) })
+        new Request(url2, { method: "POST", headers, body: JSON.stringify(args) })
       );
       return await resultFromResponse(response);
     }
@@ -37253,35 +37268,24 @@ async function handleInvoke(c, env) {
   const ctx = c.get("ctx");
   const store = c.get("store");
   const registry = new NodeRegistryStore(store);
-  if (!check(ctx, raw, "read").allow) throw TBError.notFound("not found");
-  const remote = await remotePassthroughIfMatch(c, ctx, registry, raw, null, deps);
-  if (remote) return remote;
-  let node;
-  let directTool = null;
-  try {
-    node = await registry.get(raw);
-  } catch {
-    const resolved = await registry.resolve(raw).catch(() => null);
-    if (resolved === null || resolved.node.kind !== "mcp" && resolved.node.kind !== "http" && resolved.node.kind !== "tool" || resolved.node.config === void 0 || resolved.rest === "" || resolved.rest.includes("/")) {
-      throw TBError.notFound("not found");
-    }
-    if (!check(ctx, resolved.node.path, "read").allow) throw TBError.notFound("not found");
-    node = resolved.node;
-    directTool = resolved.rest;
+  const remoteVisible = check(ctx, raw, "read").allow;
+  if (remoteVisible) {
+    const remote = await remotePassthroughIfMatch(c, ctx, registry, raw, null, deps);
+    if (remote) return remote;
+  }
+  const resolved = await registry.resolve(raw).catch(() => null);
+  if (resolved === null || resolved.rest === "" || resolved.rest.includes("/")) {
+    throw TBError.notFound("not found");
   }
+  const node = resolved.node;
+  const command = resolved.rest;
+  if (!check(ctx, node.path, "read").allow) throw TBError.notFound("not found");
   const readInvokeBody = async () => {
     const parsed = await c.req.json().catch(() => null);
-    if (directTool !== null) {
-      if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
-        throw new TBError("invalid_argument", "body must be a JSON object (tool arguments)");
-      }
-      return { tool: directTool, args: parsed ?? {} };
+    if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
+      throw new TBError("invalid_argument", "body must be a JSON object (command arguments)");
     }
-    const body2 = parsed;
-    if (!body2 || typeof body2.tool !== "string") {
-      throw new TBError("invalid_argument", "body must be {tool, arguments}");
-    }
-    return { tool: body2.tool, args: body2.arguments ?? {} };
+    return { tool: command, args: parsed ?? {} };
   };
   const toolMarker = deviceToolMarker(node);
   if (toolMarker !== null) {
@@ -37290,8 +37294,8 @@ async function handleInvoke(c, env) {
     }
     const { tool, args: args2 } = await readInvokeBody();
     const result2 = await invokeDevice(deps, toolMarker.deviceId, {
-      path: relativeDevicePath(node.path, toolMarker.mountPath),
-      tool,
+      // 帧 path 含命令叶子段:<mount 相对路径>/<命令>。
+      path: `${relativeDevicePath(node.path, toolMarker.mountPath)}/${tool}`,
       arguments: args2,
       context: deviceCallContextFrom(ctx)
     });
@@ -37312,17 +37316,13 @@ async function handleInvoke(c, env) {
     if (!check(ctx, node.path, "call").allow) {
       throw new TBError("permission_denied", `no scope grants 'call' on '${node.path}'`);
     }
-    const body2 = await c.req.json().catch(() => null);
-    if (!body2 || typeof body2.tool !== "string") {
-      throw new TBError("invalid_argument", "body must be {tool, arguments}");
-    }
-    if (body2.tool !== "exec") {
-      throw new TBError("invalid_argument", `unknown cmd '${body2.tool}' on '${node.path}'`);
+    const { tool, args: args2 } = await readInvokeBody();
+    if (tool !== "exec") {
+      throw new TBError("invalid_argument", `unknown cmd '${tool}' on '${node.path}'`);
     }
     const result2 = await invokeDevice(deps, node.config.deviceId, {
-      path: "shell",
-      tool: body2.tool,
-      arguments: body2.arguments ?? {},
+      path: "shell/exec",
+      arguments: args2,
       context: deviceCallContextFrom(ctx)
     });
     return renderResult(result2, negotiate(c.req.header("accept")));
@@ -37330,25 +37330,20 @@ async function handleInvoke(c, env) {
   if (node.kind === "context" && node.config?.kind === "context") {
     const cfg = node.config;
     await assertContextAlive(node, cfg, registry);
-    const body2 = await c.req.json().catch(() => null);
-    if (!body2 || typeof body2.tool !== "string") {
-      throw new TBError("invalid_argument", "body must be {tool, arguments}");
-    }
-    const scope = contextScopeForCmd(body2.tool);
+    const { tool, args: args2 } = await readInvokeBody();
+    const scope = contextScopeForCmd(tool);
     if (scope === null) {
-      throw new TBError("invalid_argument", `unknown cmd '${body2.tool}' on '${node.path}'`);
+      throw new TBError("invalid_argument", `unknown cmd '${tool}' on '${node.path}'`);
     }
     if (!check(ctx, node.path, scope).allow) {
       throw new TBError("permission_denied", `no scope grants '${scope}' on '${node.path}'`);
     }
     if (cfg.readOnly === true && scope === "write") {
-      throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${body2.tool}'`);
+      throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${tool}'`);
     }
-    const args2 = body2.arguments ?? {};
     if (cfg.provider === "device-fs") {
       const result3 = await invokeDevice(deps, deviceIdForDeviceFs(cfg), {
-        path: "fs",
-        tool: body2.tool,
+        path: `fs/${tool}`,
         arguments: args2,
         context: deviceCallContextFrom(ctx)
       });
@@ -37357,8 +37352,7 @@ async function handleInvoke(c, env) {
     const contextMarker = deviceMarkerOf(cfg.providerConfig);
     if (cfg.provider !== "r2" && cfg.provider !== "s3" && contextMarker !== null) {
       const result3 = await invokeDevice(deps, contextMarker.deviceId, {
-        path: relativeDevicePath(node.path, contextMarker.mountPath),
-        tool: body2.tool,
+        path: `${relativeDevicePath(node.path, contextMarker.mountPath)}/${tool}`,
         arguments: args2,
         context: deviceCallContextFrom(ctx)
       });
@@ -37367,7 +37361,7 @@ async function handleInvoke(c, env) {
     if (cfg.provider !== "r2" && cfg.provider !== "s3") {
       const local = localContext(deps, node);
       if (local !== null) {
-        const result4 = await dispatchContextCmd(local, body2.tool, args2);
+        const result4 = await dispatchContextCmd(local, tool, args2);
         return renderResult(result4, negotiate(c.req.header("accept")));
       }
       const { manifest, export: exported } = await requirePluginExport(
@@ -37387,33 +37381,29 @@ async function handleInvoke(c, env) {
         ...cfg.authRef !== void 0 ? { upstreamAuthRef: cfg.authRef } : {},
         ...deps.pluginBindings !== void 0 ? { bindings: deps.pluginBindings } : {}
       });
-      const result3 = await dispatchContextCmd(provider2, body2.tool, args2);
+      const result3 = await dispatchContextCmd(provider2, tool, args2);
       return renderResult(result3, negotiate(c.req.header("accept")));
     }
     const provider = await contextProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchContextCmd(provider, body2.tool, args2);
+    const result2 = await dispatchContextCmd(provider, tool, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind === "skillhub" && node.config?.kind === "skillhub") {
     const cfg = node.config;
     await assertContextAlive(node, cfg, registry);
-    const body2 = await c.req.json().catch(() => null);
-    if (!body2 || typeof body2.tool !== "string") {
-      throw new TBError("invalid_argument", "body must be {tool, arguments}");
-    }
-    const scope = skillhubScopeForCmd(body2.tool);
+    const { tool, args: args2 } = await readInvokeBody();
+    const scope = skillhubScopeForCmd(tool);
     if (scope === null) {
-      throw new TBError("invalid_argument", `unknown cmd '${body2.tool}' on '${node.path}'`);
+      throw new TBError("invalid_argument", `unknown cmd '${tool}' on '${node.path}'`);
     }
     if (!check(ctx, node.path, scope).allow) {
       throw new TBError("permission_denied", `no scope grants '${scope}' on '${node.path}'`);
     }
     if (cfg.readOnly === true && scope === "write") {
-      throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${body2.tool}'`);
+      throw new TBError("permission_denied", `readOnly \u6302\u8F7D\u62D2\u7EDD '${tool}'`);
     }
-    const args2 = body2.arguments ?? {};
     const provider = await skillhubProviderFor(node, cfg, deps, c.req.url);
-    const result2 = await dispatchSkillhubCmd(provider, body2.tool, args2);
+    const result2 = await dispatchSkillhubCmd(provider, tool, args2);
     return renderResult(result2, negotiate(c.req.header("accept")));
   }
   if (node.kind !== "builtin" || node.config?.kind !== "builtin") {
@@ -37422,12 +37412,7 @@ async function handleInvoke(c, env) {
   const builtins = builtinsOf(store);
   const mod = builtins.get(node.config.module);
   if (!mod) throw TBError.unimplemented(`builtin module '${node.config.module}' not available`);
-  const body = await c.req.json().catch(() => null);
-  if (!body || typeof body.tool !== "string") {
-    throw new TBError("invalid_argument", "body must be {tool, arguments}");
-  }
-  const cmd = body.tool;
-  const args = body.arguments ?? {};
+  const { tool: cmd, args } = await readInvokeBody();
   const spec = scopeForCmd(mod, node.path, cmd);
   if (!spec) throw new TBError("invalid_argument", `unknown cmd '${cmd}' on '${node.path}'`);
   if (!check(ctx, node.path, spec.scope).allow) {
@@ -37576,17 +37561,22 @@ async function handleHelp(c, env) {
   if (!check(ctx, path, "read").allow) throw TBError.notFound("not found");
   const remote = await remotePassthroughIfMatch(c, ctx, registry, path, "~help", deps);
   if (remote) return remote;
+  const builtins = builtinsOf(store);
+  const refresh = c.req.query("refresh") === "1";
+  const schemas = c.req.query("schemas") === "1";
   let node;
   try {
     node = await registry.get(path);
   } catch {
     const toolModel = await toolHelpModelFor(c, ctx, registry, path, deps);
     if (toolModel !== null) return renderHelp(await enrichHelp(toolModel, path, store), rep);
+    const cmdModel = await commandHelpModelFor(registry, ctx, builtins, deps, path, {
+      refresh,
+      schemas
+    });
+    if (cmdModel !== null) return renderHelp(await enrichHelp(cmdModel, path, store), rep);
     throw TBError.notFound("not found");
   }
-  const builtins = builtinsOf(store);
-  const refresh = c.req.query("refresh") === "1";
-  const schemas = c.req.query("schemas") === "1";
   const model = await helpModelFor(node, registry, ctx, builtins, deps, {
     refresh,
     schemas,
@@ -38556,20 +38546,6 @@ var PgSearchIndex = class extends SqlSearchIndex {
 
 // src/pgStateStore.ts
 var DEFAULT_LIST_LIMIT = 1e3;
-var MAX_CODE_POINT = 1114111;
-var SURROGATE_START = 55296;
-var SURROGATE_END = 57343;
-function prefixUpperBound(prefix) {
-  const points = [...prefix];
-  for (let i = points.length - 1; i >= 0; i--) {
-    const code = points[i]?.codePointAt(0);
-    if (code === void 0 || code >= MAX_CODE_POINT) continue;
-    let next = code + 1;
-    if (next >= SURROGATE_START && next <= SURROGATE_END) next = SURROGATE_END + 1;
-    return points.slice(0, i).join("") + String.fromCodePoint(next);
-  }
-  return void 0;
-}
 var PgStateStore = class {
   constructor(sql) {
     this.sql = sql;
@@ -38753,20 +38729,6 @@ var SqliteSearchIndex = class extends SqlSearchIndex {
 // src/sqliteStateStore.ts
 import Database2 from "better-sqlite3";
 var DEFAULT_LIST_LIMIT2 = 1e3;
-var MAX_CODE_POINT2 = 1114111;
-var SURROGATE_START2 = 55296;
-var SURROGATE_END2 = 57343;
-function prefixUpperBound2(prefix) {
-  const points = [...prefix];
-  for (let i = points.length - 1; i >= 0; i--) {
-    const code = points[i]?.codePointAt(0);
-    if (code === void 0 || code >= MAX_CODE_POINT2) continue;
-    let next = code + 1;
-    if (next >= SURROGATE_START2 && next <= SURROGATE_END2) next = SURROGATE_END2 + 1;
-    return points.slice(0, i).join("") + String.fromCodePoint(next);
-  }
-  return void 0;
-}
 var SqliteStateStore = class {
   db;
   stmtGet;
@@ -38816,7 +38778,7 @@ var SqliteStateStore = class {
   async list(prefix, opts) {
     const limit = opts?.limit ?? DEFAULT_LIST_LIMIT2;
     const lowerByCursor = opts?.cursor !== void 0 && opts.cursor >= prefix;
-    const upper = prefix === "" ? void 0 : prefixUpperBound2(prefix);
+    const upper = prefix === "" ? void 0 : prefixUpperBound(prefix);
     const conditions = [];
     const params = { n: limit + 1 };
     if (lowerByCursor) {
@@ -38853,7 +38815,7 @@ import { join as join4 } from "path";
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.10.0",
+  version: "0.12.0",
   description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite or PostgreSQL persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
   type: "module",
   license: "MIT",
@@ -38925,10 +38887,33 @@ var package_default = {
 };
 
 // src/assets.ts
+import { brotliCompressSync, gzipSync, constants as zlibConstants } from "zlib";
 import { dirname as dirname2, join as join3, resolve as resolve2, sep as sep2 } from "path";
 import { readFile as readFile2 } from "fs/promises";
 import { createRequire } from "module";
 import { existsSync } from "fs";
+var COMPRESSIBLE = /^(?:text\/|application\/(?:javascript|json|manifest\+json|wasm)|image\/svg\+xml)/;
+var MIN_COMPRESS_BYTES = 1024;
+function cacheControlFor(pathname) {
+  return pathname.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-cache";
+}
+function acceptsEncoding(accept, enc) {
+  if (!accept) return false;
+  for (const part of accept.split(",")) {
+    const [tokenRaw = "", ...params] = part.trim().split(";");
+    const token = tokenRaw.trim().toLowerCase();
+    if (token !== enc && token !== "*") continue;
+    const q = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+    if (q && Number(q.slice(2)) === 0) return false;
+    return true;
+  }
+  return false;
+}
+function pickEncoding(accept) {
+  if (acceptsEncoding(accept, "br")) return "br";
+  if (acceptsEncoding(accept, "gzip")) return "gzip";
+  return void 0;
+}
 function resolveUiDir(uiDirOverride) {
   if (uiDirOverride !== void 0) {
     return existsSync(join3(uiDirOverride, "index.html")) ? resolve2(uiDirOverride) : void 0;
@@ -38942,8 +38927,22 @@ function resolveUiDir(uiDirOverride) {
     return void 0;
   }
 }
+function toBytes(buf) {
+  const out = new Uint8Array(new ArrayBuffer(buf.byteLength));
+  out.set(buf);
+  return out;
+}
+function weakEtag(data) {
+  let hash = 2166136261;
+  for (let i = 0; i < data.length; i++) {
+    hash ^= data[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return `W/"${(hash >>> 0).toString(16)}-${data.length.toString(16)}"`;
+}
 function uiAssetsFetcher(uiDir) {
   const root = resolve2(uiDir);
+  const cache = /* @__PURE__ */ new Map();
   return async (request) => {
     const url2 = new URL(request.url);
     let pathname = decodeURIComponent(url2.pathname);
@@ -38952,14 +38951,44 @@ function uiAssetsFetcher(uiDir) {
     if (full !== root && !full.startsWith(root + sep2)) {
       return new Response("not found", { status: 404 });
     }
-    try {
-      const data = await readFile2(full);
-      return new Response(new Uint8Array(data), {
-        headers: { "content-type": fsContentTypeOf(full) }
-      });
-    } catch {
-      return new Response("not found", { status: 404 });
+    let asset = cache.get(full);
+    if (asset === void 0) {
+      let data;
+      try {
+        data = await readFile2(full);
+      } catch {
+        return new Response("not found", { status: 404 });
+      }
+      const body = toBytes(data);
+      asset = { body, contentType: fsContentTypeOf(full), etag: weakEtag(body) };
+      cache.set(full, asset);
+    }
+    const headers = new Headers({
+      "content-type": asset.contentType,
+      "cache-control": cacheControlFor(pathname),
+      "etag": asset.etag
+    });
+    if (request.headers.get("if-none-match") === asset.etag) {
+      return new Response(null, { status: 304, headers });
+    }
+    const canCompress = COMPRESSIBLE.test(asset.contentType) && asset.body.length >= MIN_COMPRESS_BYTES;
+    const encoding = canCompress ? pickEncoding(request.headers.get("accept-encoding")) : void 0;
+    if (canCompress) headers.set("vary", "Accept-Encoding");
+    if (encoding === "br") {
+      asset.br ??= toBytes(
+        brotliCompressSync(asset.body, {
+          params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11 }
+        })
+      );
+      headers.set("content-encoding", "br");
+      return new Response(asset.br, { headers });
+    }
+    if (encoding === "gzip") {
+      asset.gzip ??= toBytes(gzipSync(asset.body, { level: 9 }));
+      headers.set("content-encoding", "gzip");
+      return new Response(asset.gzip, { headers });
     }
+    return new Response(asset.body, { headers });
   };
 }
 function resolveUiAssets(uiDirOverride) {