Skip to content

feat: add durable device mailbox with unified delivery fallback - #118

Merged
Disdjj merged 3 commits into
mainfrom
review-toolbridge-pr117
Aug 28, 2026
Merged

feat: add durable device mailbox with unified delivery fallback#118
Disdjj merged 3 commits into
mainfrom
review-toolbridge-pr117

Conversation

@Disdjj

@Disdjj Disdjj commented Aug 28, 2026

Copy link
Copy Markdown
Member

Summary

  • add an encrypted, pull-only durable mailbox with CAS-backed operation state, leases, cancellation, expiry, credential revalidation, and a device-side durable journal
  • let normal command invocations select ~delivery: realtime | mailbox | fallback; fallback queues only when the host proves the realtime call was not_dispatched
  • expose the same single-call contract through the SDK, tb call, Dashboard, and MCP while keeping existing realtime Device SDK integrations unchanged
  • add operation management and device claim/renew/complete surfaces for both Node and Cloudflare hosts

Safety and compatibility

  • completed includes device business errors and never falls back to mailbox
  • unknown means the call may have reached the device; it is returned as non-retryable and is never automatically queued
  • existing commands default to realtime, so current Device SDK integrations do not need to change
  • mailbox-capable commands opt in with delivery: mailbox | both and consume work through createDeviceMailboxProcessor plus a durable journal
  • mailbox requires TB_SECRET_ENCRYPTION_KEY; this is at-rest encryption with a separately derived mailbox subkey, not end-to-end encryption
  • one active installation per deviceId remains the MVP idempotency prerequisite

Public package versions

  • @tool-bridge/app 0.19.0
  • @tool-bridge/cli 0.29.0
  • @tool-bridge/dashboard 0.26.0
  • @tool-bridge/gateway 0.24.0
  • @tool-bridge/sdk 0.20.0
  • @tool-bridge/server 0.20.0

Tags must be created one at a time from main after merge.

Validation

  • pnpm verify
  • pnpm turbo run build
  • npx -y @tokenroll/llmdoc validate
  • git diff --check

Closes #117

Disdjj added 3 commits August 28, 2026 22:16
Add a pull-only encrypted operation authority and durable device journal so offline work survives process restarts. Model dispatch as completed, not_dispatched, or unknown so fallback only queues work when the gateway can prove the realtime call never reached the device.
Let callers select realtime, mailbox, or certainty-gated fallback on the normal command call. Project the same contract through the SDK, CLI, Dashboard, and MCP so agents can request deferred execution in one operation instead of retrying through a separate enqueue endpoint.
Document the deployment trust root, pull lifecycle, journal guarantees, and single-installation boundary. Keep every public surface aligned on the single-call delivery policy and record why fallback depends on dispatch certainty rather than error codes.
@Disdjj
Disdjj merged commit aeab8ba into main Aug 28, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(device): durable pull mailbox for deferred device operations

1 participant