@tool-bridge/server 0.19.0 → 0.20.0

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

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