Adds a **Message my Bestie** action for Siri and Shortcuts. Siri asks
what to say, confirms with the Bestie's name ("Send “…” to Astra?"), and
posts the message in your DM with the Bestie, without opening Buzz. The
Bestie's reply arrives as a normal notification, in the same DM the Home
star opens.
This is the iOS 16+ App Shortcut from [ADR
0005](https://github.com/block/buzz/blob/mobile-siri-bestie-dm/docs/adr/0005-quick-send-uses-the-system-send-message-action.md).
Follow-ups, not in this PR: the iOS 27 `messages.sendMessage` schema
intent, naming other recipients, a separate "Start a chat with my
Bestie" intent for a new Solo chat, and opening Buzz with a draft when a
send fails.
### How it works
- The App Intent runs without opening the app and hands the text to Dart
over a method channel. It waits up to 20 s for Home to say it is ready,
and runs one send at a time.
- A background launch already starts the Flutter engine and builds Home
([ADR
0004](https://github.com/block/buzz/blob/mobile-siri-bestie-dm/docs/adr/0004-background-work-runs-in-the-app-engine.md)
records the measurement). So a small `QuickSendHost`, which the app
hands Home as an invisible background widget, takes the send. Nothing is
reimplemented natively.
- Before confirming, Swift asks Dart for the saved Bestie's pubkey and
name; the send then goes to exactly that agent, so a choice this phone
hasn't synced yet is caught at the confirmation.
- The send reuses the Home star's lookup for the Bestie DM (opening it
with the relay's find-or-create DM command when it isn't loaded) and
posts with the same `SendMessage` the composer uses.
- If Buzz has been in the background past its 5 s grace period, the
relay session has closed its socket. The send reopens it, then lets the
normal background pause start over.
- A message the relay rate-limits is retried (up to 3 tries); the relay
turned it away, so a retry can't duplicate it. Any other failure isn't
retried, since the message might have landed.
- The confirmation is pinned to the community and account it was shown
in: if Buzz switches either before the message goes out, the send is
refused.
- If the send fails, or Buzz can't tell whether it landed (no answer
from the relay), the message is saved as the Bestie DM's composer draft,
after any draft already there, and Siri says so ("Buzz isn't sure that
sent. Check your Bestie DM before trying again." when the outcome is
unknown). A successful send leaves the draft alone. Limits: if the DM
can't be found or opened, there is nowhere to save it and Siri says the
message wasn't saved, and the app being killed mid-send isn't covered.
- Refusals (no Bestie, offline, empty or too long, switched community)
come back as a short message Siri reads.
### Regressions
- Nothing existing changes behavior: the host only answers this method
channel, and the action does nothing until someone runs it. Its bugs
stay inside the quick send path.
- The Home star's DM lookup moved into `cachedBestieConversation`
unchanged, so the star behaves as before.
- A composer that is open on screen now shows a draft another writer
saved for it (here, a failed quick send) instead of overwriting it with
the next keystroke. It listens without rebuilding, and its own saves are
ignored.
- A background wake pays the cost of starting the app's Dart code, which
iOS already does for this launch.
### Before / after
| Before: no Buzz actions in Shortcuts | After |
| --- | --- |
| <img width="300" alt="Shortcuts Library before"
src="https://github.com/user-attachments/assets/b0870e3d-2823-4c7d-be0e-a242a3fdafd7">
| <img width="300" alt="Shortcuts Library after, listing Buzz Dev under
Apps"
src="https://github.com/user-attachments/assets/8c092006-76b9-4313-a401-68189f5674cf">
|
| Asks what to say | Confirms (names the Bestie) | Sent |
| --- | --- | --- |
| <img width="250" alt="Prompt"
src="https://github.com/user-attachments/assets/a2eaf44a-5287-48b6-9c5a-2aaefc90c0a8">
| Shows "Send “…” to *Bestie's name*?" (capture omitted: it shows an
internal agent name) | <img width="250" alt="Sent"
src="https://github.com/user-attachments/assets/07fe66e3-4480-4d06-be52-623416e567b8">
|
The DM result and a demo video show internal names, so they're shared
internally rather than here.
### Testing
- Added test, `quick_send_test.dart` journey: Home reports ready; Siri's
Bestie lookup is refused with no Bestie, then returns the chosen
Bestie's pubkey and name; a send confirmed for another community is
refused; an empty send is refused without publishing; a send while Buzz
is backgrounded and its socket closed reconnects, opens the DM with the
Bestie, survives a rate-limited first try, posts the message in that DM
tagged to the Bestie, and hands the session back to its background
pause; a second send goes to the same DM and leaves the person's draft
there as it was; a send whose answer is lost is reported as unsure and
kept in that draft after the person's own text, with its mentions; a
socket that drops just before the message goes out keeps it too; leaving
Home reports unready. Removing the rate-limit retry, the community check
or the draft save fails it.
- Extended the composer's share-delivery journey: a draft saved by
another writer while the composer is open shows in the composer and
survives the next keystroke, and survives an ordinary send that was
pending when it arrived and then fails. Removing the composer's listener
or its revision bump fails it.
- iPhone 17 Pro simulator (iOS 27), Builderlab community with a Bestie,
automated with AXe:
- Cold: Buzz terminated, ran the action from Shortcuts, the confirmation
named the Bestie, "Sent.", and the message was in the Bestie DM with its
reply. No Solo chat was created.
- Warm: Buzz in the background for 10 s, ran it again, "Sent.", same DM.
- At-risk flows: sent a typed message from the DM composer, went back to
Home, and the Home star reopened the same DM.
- `just mobile-check mobile-test` passes.
buzz-review-completed
---------
Signed-off-by: Tom Brow <tomb@squareup.com>
Co-authored-by: Tom Brow <tomb@squareup.com>
Buzz Mobile
Flutter mobile client for Buzz.
See VISION_MOBILE.md for intended behavior and architecture.
Builderlab builds
Three build-time settings, passed with Flutter's --dart-define (shell
environment variables alone are not read), choose the build's single
Builderlab. Set all three or none:
flutter run \
--dart-define=BUZZ_DISTRIBUTION=public \
--dart-define=BUZZ_BUILDERLAB_URL=https://app.builderlab.xyz \
--dart-define=BUZZ_BUILDERLAB_RELAYS=communities.buzz.xyz
BUZZ_DISTRIBUTION:publicorinternal. See the public build and internal build, and ADR 0001.BUZZ_BUILDERLAB_URL: the build's Builderlab HTTPS origin. On iOS, sign-in currently opens only Builderlab's own hosts (app.builderlab.xyz, or a<tenant>.builderlab.xyzorganization) and their staging equivalents; the native browser bridge refuses any other origin.BUZZ_BUILDERLAB_RELAYS: comma-separated DNS domains whose relays use that Builderlab's session. Entries match the domain itself and its subdomains, case-insensitively. Use DNS names, not URLs or wildcards.
With none set, Builderlab features are disabled: no account login, community creation, backup/recovery UI, reconnect prompts, or background account restoration. QR/code pairing, community links and invites use Nostr-only entry. Saved account keys and sessions are retained for a later enabled build.
A public build signs in with Builderlab's web account setup, and requires it for
communities under BUZZ_BUILDERLAB_RELAYS, which also places new communities
under the first domain. QR pairing and other communities stay available.
An internal build offers one Sign in action that goes to the organization's
single sign-on and then joins the community at its
BUZZ_BUILDERLAB_RELAYS host. It has no QR pairing, community switching or
community creation, refuses links to other relays, and hides communities on
other relays that an earlier build saved, keeping their keys.
An internal build takes exactly one BUZZ_BUILDERLAB_RELAYS entry, its
organization's relay host. It matches that exact host, not a domain, and the
relay always receives its Builderlab session's relay assertions.
Agent creation links
buzz://agent/new?card=<id> opens the Agents page and an editable, pre-filled
Create agent form for the active community. Opening a link never creates an
agent. A Builderlab agent card's QR leads to its share page
(app.builderlab.xyz/a/<id>), whose Add to Buzz button opens this link.
The app fetches <avatars CDN>/<id>/agent.json from the CDN for this build's
Builderlab environment (HostedEnvironment.avatarsCdnOrigin), never from a
host named by the link. The link carries only the id, so the QR stays small
however long the instructions are.
{
"id": "<id>",
"name": "Scout",
"avatarUrl": "https://<avatars CDN>/<id>/<revision>/avatar.png",
"instructions": "Reply concisely.",
"model": "<model catalog id>",
"reasoningEffort": "high"
}
id(the link's card id),nameandavatarUrl(anhttpsURL) are required.instructions,modelandreasoningEffortare optional and left for the user when absent. A missing required field or a known field of the wrong type makes the card invalid, and no form opens. Other keys, includingvanddescription, are ignored whatever their type. The card id is opaque to the app.- Prefilled values are only a draft: Create applies its usual rules, so a name outside 1 to 64 letters, numbers, spaces, dots, hyphens or underscores, or instructions over 20,000 characters, must be edited before Create succeeds.
- The fetch shares the image loader's limits (
lib/shared/utils/bounded_fetch.dart): it is aborted after 20 seconds without a byte or 5 minutes overall, and a card over 2 MB is rejected. modelandreasoningEffortare pre-selected only if the live model catalog offers them (the effort only for that model).- The link waits for sign-in and community load. It needs Builderlab login and a hosted community that supports remote agents. It reloads the signed-in account's agents first, and is dropped with a message if an unfinished agent setup exists (resume or discard that first) or the card can't be loaded.
- A link that arrives while Agents is open replaces it only when the list is all that's showing. With a form, profile or dialog open, the link is dropped with a message so unfinished work is kept.
The parser is lib/shared/deeplink/agent_creation_link.dart; the card reader
is lib/features/agents/agent_creation_draft.dart.
Hosted relay authentication
--dart-define=BUZZ_HOSTED_RELAY_AUTH=true enables Builderlab relay assertions
and reconnect sign-in for a public build's BUZZ_BUILDERLAB_RELAYS. It
defaults off: configure backend assertion issuance before enabling mobile
authentication, and enable relay enforcement last.
Setup
Use the Flutter SDK pinned by the repository. Activate Hermit from the repo root before resolving packages or running any Flutter command:
cd /path/to/buzz
. ./bin/activate-hermit
./bin/just mobile-install
mobile-build-android intentionally builds with --no-pub. If an IDE or an
external Flutter SDK has touched mobile/.dart_tool, rerun mobile-install
with the pinned SDK before building so flutter_test, sky_engine, and the
engine all come from the same Flutter version.
iOS toolchain
Use Xcode 27.1 for iOS development and build validation on an Apple silicon Mac running macOS Tahoe 26.6 or later, as required by the Xcode 27 release notes. On Intel Macs or hosts that cannot meet those requirements, use a compatible Xcode 26 version, which remains supported. Activate the repository's pinned Flutter SDK with Hermit as described above.
When multiple Xcode versions are installed, select the intended version for
the command with DEVELOPER_DIR, for example:
DEVELOPER_DIR=/Applications/Xcode-27.1.0.app/Contents/Developer xcodebuild -version
Adjust the path to your installation. Keep the compiler and SDK from the same
Xcode installation. The pinned Flutter native-assets tooling can discover the
globally selected SDK even when DEVELOPER_DIR selects another compiler, so
use a build machine with a matching default Xcode when validating either
Xcode 26 or Xcode 27.
The native cryptography dependency is pinned upstream C source in
ios/BuzzPushKit/Sources/CSecp256k1; it requires no Swift build-plugin approval.
GitHub's mobile CI currently uses the Xcode default of its macos-latest
runner. The internal release toolchain is configured separately in
buzz-releases.
Run
# From repo root (applies a worktree-isolated debug identity and starts/reuses Simulator):
just mobile-dev
# Direct (uses the app's configured community; apply worktree overrides first):
cd mobile && flutter run --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
Worktree-aware debug identity
Debug builds produced from a git worktree get a unique app identifier keyed
to the worktree directory name
(xyz.block.buzz.dev.mobile.<slug> on iOS,
xyz.block.buzz.mobile.<slug> on Android) plus a display-only branch label
in the app name (Buzz (my-branch), or a short SHA when the worktree is
detached). Because the identifier follows the directory rather than the
branch, one worktree keeps exactly one installed app — and its login state —
across branch switches, and builds from multiple worktrees install side by
side, mirroring the desktop dev experience. Release and profile builds
always keep the production identity and name.
just mobile-dev and just mobile-build-android apply this automatically by
running scripts/mobile-worktree-overrides.sh, which writes two gitignored
files:
mobile/ios/Flutter/WorktreeOverrides.xcconfig(included by Debug builds only; a developer'sAppOverrides.xcconfigis included after it, so app-specific overrides like a personalBUNDLE_IDENTIFIERfor device signing always win)mobile/android/worktree.properties(read by the debug build type only)
Android developers can keep a stable local test identity that takes precedence
over the generated worktree values by creating the gitignored
mobile/android/AppOverrides.properties:
appName=Buzz Pairing
applicationIdSuffix=.device_pairing_e2e1
These values are consumed by the debug build type only. The standard
just mobile-build-android command can still be used; regenerating
worktree.properties does not overwrite AppOverrides.properties. Release
and profile builds keep the production Buzz name and application ID.
For direct Xcode / Android Studio / flutter run development, run
./scripts/mobile-worktree-overrides.sh from the repo root once per branch
switch to refresh the display label (the install identity never changes);
the persisted files are then picked up by any subsequent build. In the main
checkout the script is a no-op that removes stale override files, restoring
the plain Buzz identity. To enable push in direct Xcode builds and Runner tests, supply a
BUZZ_PUSH_GATEWAY_URL build setting in the gitignored
mobile/ios/Flutter/AppOverrides.xcconfig; the build phase validates and
passes it through as a Flutter Dart define. Since // begins an xcconfig
comment, spell the origin as BUZZ_PUSH_GATEWAY_URL = https:/$()/push.example.
For an Android debug build that must remain installed alongside other Buzz worktree builds, set an explicit launcher name and package suffix when invoking the generator or a recipe that invokes it:
BUZZ_PUSH_GATEWAY_URL="https://push.example" \
BUZZ_ANDROID_DEBUG_APP_NAME="Buzz Huddles" \
BUZZ_ANDROID_DEBUG_ID_SUFFIX=".huddles_829c" \
./bin/just mobile-build-android
This example produces the debug-only package
xyz.block.buzz.mobile.huddles_829c with the launcher label Buzz Huddles.
The suffix must start with a dot followed by a lowercase letter and may contain
only lowercase letters, digits, and underscores. Release and profile builds
ignore these overrides and retain the production package and name.
To remove leftover worktree-suffixed installs from booted iOS simulators and
connected Android emulators, run just mobile-clean (add --dry-run via
./scripts/mobile-worktree-clean.sh --dry-run to preview). Production
installs are never touched.
iOS push capability
Every iOS artifact builds and embeds the Notification Service Extension and
native push bridge. Runtime activation is fail-closed and scoped to the current
relay. After authenticated connectivity and a fully valid NIP-11 buzz-push-v1 push
descriptor, Buzz independently requests display permission and registers with
APNs. Display denial or request failure does not gate the device token, gateway
enrollment, or lease publication, so a later user opt-in can display pushes
without rebuilding transport authority. An absent, malformed, or unreachable
descriptor leaves push inactive without partial enrollment.
Mobile builds without a gateway origin succeed with push unavailable. To enable push, supply the gateway origin explicitly:
flutter build ios --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
flutter build apk --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
The iOS and Android build gates validate any supplied define, rejecting empty or malformed values. Release/profile builds require an HTTPS origin without an explicit port. An absent define disables permission requests, APNs registration, gateway enrollment, and lease publication; Settings shows push as unavailable. No production gateway is selected implicitly. Enrollment grants and crash-recovery journals are scoped to this origin. Push has not shipped to existing users, so there is no legacy-state or cross-gateway migration. Changing gateways requires fresh enrollment; old installations expire under their original gateway's lease policy. Current-gateway response loss is still retried from the exact journaled request.
Relay rollout remains an explicit deployment opt-in. Only deployments with
BUZZ_PUSH_ENABLED=true advertise the descriptor and process push. See
docs/push-gateway-deployment.md for the canonical gateway profile contract,
manual physical-device proof, measurements, and rollback procedure.
For local physical-device development, override the identity and sandbox
environments in the gitignored mobile/ios/Flutter/AppOverrides.xcconfig:
BUNDLE_IDENTIFIER = com.example.buzz.mobile
BUZZ_DEVELOPMENT_TEAM = YOUR_TEAM_ID
BUZZ_IOS_PUSH_ENVIRONMENT = development
BUZZ_APP_ATTEST_ENVIRONMENT = development
BUZZ_PUSH_GATEWAY_URL = https:/$()/push.example
Use your personal bundle ID and team above. Provision both the parent and its
.NotificationService extension. Configure an isolated gateway with the matching
App Attest application ID, APNs topic and sandbox certificate. Development
attestation requires the explicit personal-dev-app-attest gateway build feature
and BUZZ_PUSH_APP_ATTEST_ENVIRONMENT=development; ordinary gateway builds accept
production attestation only. See docs/push-gateway-deployment.md.
Validate distributed builds separately using a signed release candidate and
its matching gateway configuration.
Parent app identifiers require Apple's Communication Notifications capability and a regenerated app provisioning profile. The Notification Service Extension profile does not require that capability. Enable it on the personal development App ID for local rich-presentation validation. Enabling it on distribution App IDs is a release follow-up and is not performed by this repository change. Without a matching parent profile, source and unit validation still work, but the app cannot be signed for a physical device.
APNs and the gateway continue to carry only the constant opaque wake-up. The extension fetches the message from the scoped relay, verifies message, sender profile, and channel-metadata signatures, and uses a bounded App Group cache for names and app-rendered avatar thumbnails. It never fetches an avatar URL; missing, stale, or invalid enrichment falls back to the verified message with a short sender pubkey, community subtitle, and no image.
Checks
dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test
Or from the repo root: just mobile-check and just mobile-test.
When writing tests, favor a few journey tests that drive real user flows over many small logic tests. See Testing Conventions.
Android release signing
Android release builds fail unless all upload-key inputs are supplied through the environment:
BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH: path to a CI-vended keystore fileBUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORDBUZZ_ANDROID_UPLOAD_KEY_ALIASBUZZ_ANDROID_UPLOAD_KEY_PASSWORD
The keystore path must be absolute, and the keystore must remain outside the repository. Development and debug builds do not require these variables.
Release pipelines that sign through the central APK Signer service instead of
a local upload keystore must set BUZZ_ANDROID_RELEASE_SIGNING=external. That
mode produces an unsigned release bundle and refuses to run if any
BUZZ_ANDROID_UPLOAD_* value is also set.
Architecture
lib/
├── main.dart # Entry point, Riverpod bootstrap
├── app.dart # MaterialApp with theme
├── shared/
│ └── theme/ # Catppuccin light/dark, spacing tokens, extensions
└── features/
└── home/ # Placeholder home surface
- State management: Riverpod + Hooks (
HookConsumerWidget) - Theme: Catppuccin Latte (light) / Macchiato (dark) — matches desktop
- Spacing:
Gridtokens for consistent spacing - Linting:
flutter_lints+riverpod_lintviacustom_lint - Feature isolation: No cross-feature imports except
shared/