Native mobile clients
Architecture decision Suzent mobile uses SwiftUI on iOS and Kotlin/Jetpack Compose on Android. Both applications live in this monorepo; Python remains managed by uv, Android by Gra
此页面目前提供英文内容,中文翻译尚未完成。
Architecture decision
Suzent mobile uses SwiftUI on iOS and Kotlin/Jetpack Compose on Android. Both applications live in this monorepo; Python remains managed by uv, Android by Gradle, and iOS by Xcode/Swift Package Manager. Existing desktop paths stay intact. The clients share a wire contract and fixtures, not a cross-platform UI runtime.
The desktop backend owns agent execution, memory and chat history. Mobile has two independent roles: a remote client and an opt-in foreground device Node. A Node grant does not authorize HTTP access. No Python runtime runs on the phone.
Status
The first increment is a developer preview, not a release-ready mobile product. What it covers is described under Run and Preview flow; what it does not is under Limits.
Mobile uses a separate, revocable client credential issued after desktop approval. In desktop Settings → Devices → Mobile access, choose the shared conversations and actions, then generate a short-lived QR invitation. Scan it in the native app (or paste the invitation), review the desktop name and server-provided permissions, and confirm the connection on the phone. There is no second desktop approval. Closing the QR cancels an unused invitation; issued device credentials can be revoked separately. Abrupt desktop termination or network loss falls back to the five-minute invitation expiry. Old invitations retain the code-comparison flow. Host and peer-agent tokens are not accepted as mobile credentials. Existing preview connections must pair again. See the pairing contract.
Planned work is tracked in the Roadmap.
Layout
apps/ios/ SwiftUI app + XcodeGen project specification
apps/android/ Compose app + Gradle project
packages/mobile-contract/ Protocol description and cross-language fixtures
packages/SuzentCore/ Foundation-only Swift protocol/client packageRun
Use a backend with mobile pairing/client protocol 1 and snapshot/cursor protocol 1. The phone checks capabilities before connecting and reports incompatible versions.
Enable desktop Settings → Mesh → Network access, restart, and use its LAN/Tailscale address on port 25314 (never the phone's localhost) in the desktop pairing card. The QR includes the preferred origin plus discovered LAN/Tailscale candidates. Updated phones check candidate capabilities without credentials, then display the first reachable compatible address for confirmation. A three-second timeout per candidate bounds this check. Old single-origin invitations remain supported. Select permissions on desktop, then pair and confirm on the phone. Saved connections retain the confirmed address and the invitation's alternative addresses. On both platforms, reconnect probes saved addresses without credentials with a three-second timeout per address, including legacy HTTP connections in debug builds. The entire reconnect has a twenty-second deadline and a Cancel action. Cancellation also stops pending network requests; moving to the background cancels reconnect. An unreachable desktop leaves the saved connection intact so the user can retry or pair again. HTTPS/WSS is required for release builds. Debug builds allow explicit HTTP addresses for a trusted LAN/tailnet; HTTP is not encrypted. No certificate-validation bypass or automatic URL redirect is supported.
Several desktops
A phone can hold credentials for several desktops but is connected to one at a
time. Both platforms store one encrypted record of saved desktops
({activeId, desktops: [{id, name, connection}]}): a single Keychain item
(account "desktops") on iOS, the existing Keystore-encrypted preference on
Android. A record from a single-connection build is read as one active desktop
and rewritten; on iOS the old "primary" item is then deleted. The id is a
local UUID. The name comes from the pairing preview and is refreshed from the
optional desktop_name in /mobile/client/session, falling back to the origin
host.
Pairing re-pairs the active desktop for Pair again. Otherwise it looks for a
saved desktop that matches the invitation: the same device-CA fingerprint when
both have one, else any shared normalized origin. Only that desktop's token
feeds the repair proof, rotation and reuse checks. A match replaces the entry;
no match adds one. Switching probes and loads the target with the usual
three-second-per-address and twenty-second limits before it resets any session
state, so an unreachable desktop leaves the open session untouched. A 401 forgets
only the desktop that returned it. Node tokens and remembered model choices stay
per connection. The pure list logic lives in Desktops.kt and
SuzentCore/SavedDesktops.swift, with unit tests on both platforms.
Phones show a bottom bar with Chats, Inbox and Settings. It's hidden while a
conversation is open. The desktop card at the top of Settings opens the Desktops
page (switch, swipe to forget, pair another). Tablets keep the split view with
the settings button in the sidebar. The Chats list shows one of Recent (pinned,
then the recent page) or Projects at a time, picked with lightweight Recent / Projects text tabs above
the list; iOS keeps the choice in @AppStorage("homeListMode"), Android in
saved state. The sidebar can be hidden on iPad from its header and shown again from the detail
toolbar. Scheduled tasks on both platforms open from the clock button in the Inbox header.
On phones a header search icon (beside the New conversation icon) opens a separate search page
(iOS: a Route.search pushed under the conversation; Android: a searching
flag that replaces the tab home). Its query survives opening a result, so back
from that chat returns to the results; Cancel or back from the page clears it.
Tablets keep the inline sidebar field.
Inbox and shared read state
Both clients offer an Inbox with the desktop's filters (All, Notifications,
External, Agent; the page request's category), a thread page, shared unread
counts, read actions and links to target conversations. Tasks opens from the
header's clock button and Mark all read from its check button. Phones use the
Inbox tab; iPad opens it as a sheet from the sidebar toolbar, and Android tablets
switch the sidebar between Chats and Inbox. English and Chinese labels
are included. Tasks reuses the scheduled task list, including run state, next run
time, conversation links and expandable child sessions. It remains available on
older backends without the mailbox capability. Only notifications contribute to
the Inbox badge or the Mark all read action. Inbox pages resolve their target
chat ids through the existing scoped chat-status API, so destination cards show
actual conversation titles and project names rather than the event summary.
Targets missing from that response have a disabled unavailable state.
The conversation list and the Android tablet sidebar share each platform’s SuzentSegmentedTabs
component. It owns sizing, colors, selection animation, disabled state and
accessibility; pages supply typed options, localized labels and selection
callbacks. Inbox filtering and task loading remain page responsibilities.
core/mailbox_threads.py owns the shared presentation contract returned by both
mailbox APIs: threadKey, title, source, context, icon, activity, and
detail. Keys are opaque hashes of source-scoped identities. Webhooks can supply
thread_id and subject (plus optional context, semantic activity, and
detail) in their JSON body. Without an explicit subject, source kind/name and
routing signature form the thread. Agent messages use their participant pair.
The GitHub adapter resolves repository/PR/issue identity and label details only
on the backend; legacy stored summaries are supported there too.
Desktop, Android and iOS only group by the returned key. They never infer thread
identity or parse a provider payload. Missing presentation from older backends
falls back to one row per item. Semantic activity codes are localized by each UI.
mailbox-thread-fixtures.json verifies the same contract across clients and Python.
Source-specific regression cases live in the backend tests.
MailboxEventCard holds the shared pieces on each native platform: the count
badge (also used by the tab bar), the source mark chosen from sourceKind, the
status pill chosen from status, the thread row and the thread page. Status
colors come from the info and warning presentation tokens next to danger.
iOS pushes the thread page as Route.mailbox(key) (a String path inside the
iPad sheet); Android swaps it in place with a back handler, keeping it in saved
state so returning from a conversation lands on the thread.
Newest IDs sort first and duplicate IDs are removed. Opening a thread sends all
its loaded unread IDs to the existing read endpoint in batches of at most 100.
Authorization filters rows before presentation; no hidden thread counts or routing
metadata are exposed. Counts cover loaded events rather than full server history.
Reaching the last row extends the window by 50. Refresh
fetches the loaded window from offset zero and replaces it atomically on success,
so shared read changes and removed events propagate.
The /mobile/client/mailbox/page and /mobile/client/mailbox/read endpoints
reuse paired-device authentication and chat grants. Full-chat grants see global
events; limited grants see only events linked to permitted target chats. The same
scope is applied before pagination, counting and marking all read. Read-only
access is sufficient to mark messages read. The desktop's existing
mailbox_items.read_at is the shared source of truth; the background notification
drain is not used. Session capability mailbox: 1 gates the feature on older
backends. See the wire contract.
Inbox refresh uses the existing ten-second foreground navigation poll, plus opening the view, resuming and manual refresh. The desktop inbox also refreshes while visible. Neither listing nor polling marks messages read; expanding a notification or explicitly choosing a read action does. Device switches clear state and ignore stale responses. Failed writes remain unread until a successful refresh confirms the server state. No APNs/FCM or push gateway is involved.
iOS
Install full Xcode and XcodeGen. From apps/ios, run xcodegen generate, open
Suzent.xcodeproj, choose a signing team and run the Suzent scheme. The generated
project is disposable; edit project.yml. iOS 17+ is required. Set a unique bundle
identifier and signing configuration for distribution. Tokens use a
device-only Keychain item; no credentials are stored in UserDefaults.
Run the Foundation protocol tests with the Swift testing frameworks from Xcode:
swift test --package-path packages/SuzentCoreCommand Line Tools alone can build the core package (swift build --package-path packages/SuzentCore), but some installations lack the complete Testing framework
needed by swift test.
Android
Install JDK 17 and Android SDK 36. Open apps/android in Android Studio or run
./gradlew :app:assembleDebug :app:testDebugUnitTest. Android 8/API 26+ is required.
Debug builds install as Suzent Dev (com.suzent.mobile.dev, version name -dev), beside a
Play Store copy they could not replace because they are signed with the local debug key; the dev
app keeps its own pairing.
Tokens are encrypted with an Android Keystore AES-GCM key; app backup is disabled.
Preview flow
-
Pair with the desktop and open a shared chat. New conversations require the corresponding permission; send and stop permissions are independent. The phone’s Access page shows the grant and the separate Node controls.
-
Send text.
/mobile/client/sendstarts work on the backend, independently of the screen./mobile/client/livesupplies transient text; the persisted transcript is authoritative. Mobile usesprotocol: 1, sharing desktop's authoritative snapshots and sequence cursors. Reconnects resume from the last applied event, deduplicate retransmissions and replace transient text when a fresh snapshot arrives.STREAM_ENDconfirms persistence; the received response stays visible until saved history has loaded. See Stream recovery. While a turn runs, the composer offers redirect and queue in place of Stop once there is typed content, matching desktop's Enter and Cmd/Ctrl+Enter.POST /mobile/client/steer(session capabilitysteer: 1, requires bothsendandstop) forwards text and an optional model to/chat/steer-send, or to/chat/sendwhen the turn already ended. On acceptance the client cancels its current live stream, keeps the partial reply on screen (running or approval-pending tools end as errors, as on desktop) and subscribes again. Queued messages live only in the phone's memory, per conversation; the open conversation releases the next one through the normal send path once it is idle (not streaming, not running, no pending approvals). A failed release or redirect returns its text and attachments to the composer instead of the queue, so a failing desktop is not retried in a loop. The native clients subscribe immediately after send acknowledgment, showing the accepted user message locally while the backend remains authoritative. Live text is published in 50 ms batches, with a final flush on completion or failure. Network events accumulate away from the UI thread; only display batches reach the native views. Android finishes each off-thread Markdown parse before rendering the latest pending text, so frequent deltas cannot keep cancelling a long parse. Both clients memoize saved transcript presentation. Live growth follows the bottom without restarting a layout/scroll animation on every batch. Streamed prose uses the same opaque Markdown renderer as saved messages, without per-fragment fades or a synthetic cursor inserted into the document. Android skips rebinding a native text view when its rendered content and styling are unchanged. Android tables retain the original Markwon table theme and row spans. A native text view prepares table row measurements before visible layout, rather than showing unmeasured rows and correcting their heights on the next frame. The scoped title index does not load transcripts/checkpoints; mobile detail reads omit desktop context-budget computation and return currentisRunningstate. Completion reconciles that state in both the selected chat and list so the stop control cannot retain a stale list flag. -
On foreground return, refresh the transcript. A dropped stream does not automatically resend the message. A lost send acknowledgment has an unknown outcome: inspect history before sending again.
-
Enable Node separately, then approve its pairing code on the desktop. Invoke
device.statusfrom the desktop to verify the phone role. -
Backgrounding disconnects Node. Foregrounding reconnects an enabled Node. Disabling Node closes the connection but retains its pairing credential. Forgetting the connection asks the desktop to revoke the device, then removes local credentials.
Limits
The preview renders Markdown replies, PUA/ASCII citation markers, and structured
tool/reasoning activities in expandable activity rails. Citation and ordinary
web links open a native source-preview sheet with title, snippet, copy-link and
external-browser actions. Reading a source uses Safari View Controller on iOS
and Custom Tabs on Android. Inline citation capsules display source favicons
with a fixed-size fallback; repeated references have independent selection.
Multi-source citations list each resolved source in the sheet. Some legacy inline tool formats still require desktop; A2UI surfaces render natively (see Inline surfaces). Shared palette and filtering
rules live in packages/presentation; regenerate platform files with
uv run python scripts/generate_presentation.py after editing their source.
Mobile logo geometry is generated from frontend/public/favicon.svg, including
the perspective-projected eyes on the animated start-page cube.
Both launchers use the approved white-background cube-and-hand artwork in
packages/presentation/assets/mobile-icon.png. Regenerate their opaque PNGs with
uv run python scripts/generate_app_icons.py on macOS (uses sips). Android keeps
the artwork inside the adaptive icon safe area and retains the canonical eyes
for its monochrome themed icon. The in-app logo remains generated from the SVG.
It lists up to 1,000 conversations permitted by the device grant. Replay is bounded and in-memory; it is not a durable
event cursor or an always-online phone. An observer reconnects up to five times with capped backoff. Mutation requests
are never automatically retried. Exhausted recovery preserves received text.
Test coverage
Both platforms test protocol/URL validation and shared display/recovery fixtures. Android additionally tests authenticated HTTP/SSE, safe GET recovery, no mutation retries and interrupted-observer cursor recovery. The backend side covers independent observers, disconnection, overflow recovery, and snapshot handoff, terminal save confirmation and compatibility with legacy clients. Desktop TypeScript checks and its display tests run in the same suite.
Not covered, and required before any release: physical-device lifecycle, TLS, Node pairing, and end-to-end concurrent generation. Full native builds and simulator/device smoke tests are release gates in addition to the protocol unit tests — CI definitions do not imply a successful remote run.
Manual matrix, to run on both platforms: denied/revoked tokens; wrong address; background during generation; return after completion; stopped task; lost send acknowledgment; Node pending/approved/rejected; capability invocation; background disconnect; forget/re-pair; TLS failure. Never put real credentials into fixtures or logs.
Running the iOS simulator
For an interactive simulator run, keep local signing enabled so Keychain works:
xcodegen generate --spec apps/ios/project.yml
xcodebuild -project apps/ios/Suzent.xcodeproj -scheme Suzent \
-sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
-derivedDataPath /tmp/suzent-ios-build CODE_SIGN_IDENTITY=- CODE_SIGNING_ALLOWED=YES buildUnsigned CI builds check compilation only; launching an unsigned app can fail
Keychain access. The simulator uses the same pairing flow as a physical device.
For a backend on the same Mac, generate an invitation for http://127.0.0.1:25314
and paste it into the simulator app. HTTP is debug-only. Simulator cameras may be
unavailable; paste uses the same protocol and operator approval as camera scanning.
Visual foundation
Both native apps use the desktop palette, square outlines, 2-unit borders and hard
shadows. Shared spacing and type-scale constants also live in
packages/presentation/tokens.json. Pairing, conversations, chat and access are
separate views. Both apps use the centered SUZENT wordmark, blue primary actions,
flat conversation rows and an outlined composer. Assistant messages carry the
robot badge; inline code uses yellow highlights and top-level code blocks have
black language headers with horizontally scrollable light bodies. User messages
use a neutral surface so yellow retains its emphasis role. Keyboard and camera
permission prompts stay native. iOS uses VisionKit QR recognition; Android uses embedded
ZXing, which needs no Google Play services and sends nothing off the device. Neither
scanner saves an image. Both apps provide English and Simplified Chinese strings.
Platform interactions stay native where the system already defines them. On iOS the
conversation list is the root of a NavigationStack (edge swipe back), and regular
width uses NavigationSplitView; Android animates list to detail under
PredictiveBackHandler and shows both panes from 840 dp. Conversation rows have a
context menu plus swipe actions (pin/unpin, delete with confirmation). Settings is a
native grouped list. Destructive confirmations use system alerts; rename and
edit-and-resend use sheets. Errors appear as a transient toast above the composer
(or at the bottom elsewhere), while pending approvals are pinned above the composer.
Only the latest message shows its action row; every message offers the same actions
(copy, share, edit, retry, branch, sources) from a long-press menu on its footer or
bubble, so message text keeps native selection. Send, copy, long press and approval
choices give haptic feedback, and iOS text follows Dynamic Type.
Tool media
The mobile chat load (src/suzent/mobile/media.py) adds media:[{id,kind,name}] to each
finished, successful tool part that produced or read media: saved_paths of
generate_image, edit_image, check_video, speak and send_file, and
visual_path of analyze_visual. Only send_file may hand over any file type (kind
file, served with a content type guessed from its name); the others are limited to
image, video and audio extensions. A send_file whose chat-app upload failed still
counts, because its saved_paths are files that exist on the desktop (the desktop
gallery and the Artifacts panel show them too); a call rejected before that carries no
saved_paths. The id is the first 32
hex digits of the path's SHA-256, so the phone never learns desktop paths.
GET /mobile/client/chats/{id}/media/{media_id} re-scans the stored transcript for a
matching path, resolves it with the same PathResolver the desktop's /sandbox/serve
uses, and returns a FileResponse (Range requests work, which the relay streams).
Anything not reported by a media tool in that chat is a 404.
Clients render the items under a turn's activity summary, outside the collapsed rail.
Images and videos appear together in static thumbnails, one per row, without visible
filenames or horizontal gestures in the transcript. Tapping opens a full-screen pager with an item counter; swiping moves
between the group’s images and videos. Image zoom/save/share remain available,
and a video player is disposed or paused when its page leaves selection. Audio
keeps a static play entry. Video previews fetch through the existing media cache and
generate a JPEG of at most 320 px per side without creating a player. Android
limits background video preview work to two items at once. Cached previews are
reused, and extraction failure keeps the play placeholder usable. Tapping opens a
dedicated player, reuses or downloads the item, and exposes native playback controls;
closing the player or backgrounding the app pauses playback. Images keep their
inline preview and full-screen viewer. Each downloaded item is cached (cacheDir/media/<desktop>/ on
Android, Caches/media/<desktop>/ on iOS) and played from the local file: Android uses
VideoView with MediaController for video and MediaPlayer for audio, iOS uses
AVKit's VideoPlayer for both. Downloading first keeps playback independent of the
transport, since neither system player can speak the relay tunnel. Android audio
preparation is asynchronous so opening a clip does not block the UI. Items of kind
file download only when tapped, keep their original name under <id>/, and open the
system share sheet (Android through the existing FileProvider). Images are decoded
at most 1600 px on the long side. Live turns show media once the saved transcript loads.
Conversation info and phone preferences
GET /mobile/client/chats/{id}/overview (session capability chat_overview: 1) returns
the desktop sidebar's plan and context sections for one permitted chat: the chat's goal,
its tasks with status only (blocked is derived from blocked_by, as on the desktop),
and a context headline. The headline uses the stored context_usage (provider count,
else total tokens) against resolve_context_limit for the chat's model, plus the
breakdown's non-empty categories and reserve. Unlike the desktop chat load it never
deserializes agent state to estimate a missing count, so a chat with no usage reports
usedTokens: null. Clients skip the panel on older backends and in Regent's chat.
A header button opens the panel. iOS uses .inspector, which is a medium/large sheet
on compact width and a trailing column on regular width; Android uses a
ModalBottomSheet on phones and a sidebarWidth column beside the conversation from
840 dp. The panel polls every 4 s while the chat runs and every 15 s otherwise. The
offline demo returns a sample plan for its trip conversation from demo.json.
Settings → Preferences is local to the phone. iOS stores appearance, text size and
haptics in @AppStorage and applies them at the root with preferredColorScheme and
dynamicTypeSize; suzentFeedback gates every sensoryFeedback. Language opens the
app's page in iOS Settings. Android keeps them in the app_preferences file through
AppPreferences; AppPreferencesProvider overrides LocalConfiguration.uiMode (so
each isSystemInDarkTheme follows it) and scales LocalDensity.fontScale, and
suzentHaptic returns early when haptics are off. Language uses LocaleManager
per-app locales on Android 13+ with res/xml/locales_config.xml.
Inline surfaces
Agent-rendered A2UI surfaces (render_ui, ask_question) arrive in saved messages as
{"type": "a2ui", "surface": …} parts and live as CUSTOM a2ui.render events on the
same /mobile/client/live stream; a2ui.resolved removes an answered deferred question.
Both clients decode the component tree (A2UI.swift, A2UI.kt) leniently: an unknown or
malformed component becomes unknown and renders nothing, so a newer desktop never breaks
a transcript. A surface is its own chunk in the reply, counts as part of the final reply
rather than the folded activity, and a later render of the same id replaces the earlier
one in the live buffer. Every desktop component has a native view: text (markdown through
the chat renderer), badge, button, table (scrolls sideways), form (text, number, select
with optional free text, multiselect chips, checkbox, textarea; required fields gate
submit), list, progress, divider, card, stack and columns (side by side only when each
column gets at least 140 pt/dp, otherwise stacked). HTML runs in a WKWebView with a
non-persistent data store or a WebView without file, content or DOM storage access,
gets a phone viewport and standards mode when it has none, opens followed links in the
browser, and bridges postMessage({type: 'a2ui:action'}) back as an action. It always
sizes to its content with the desktop's auto-size shim (body height, re-measured on
resize, DOM changes, image loads and fonts, capped at 5000 pt/dp); an agent-given
height is only the first guess, because scrolling inside the page would fight the
chat's own scroll. Surfaces with target: "canvas"
also render inline until the conversation panel shows them.
Actions follow the desktop dispatcher. An ordinary button or form is sent through
/mobile/client/send as the desktop's [canvas: action] "label" {context} message
(sorted keys, with surface_id added); submit_question forms send the
"question: answer" text; a deferred ask_question posts to
POST /mobile/client/surface-answer (session capability surfaces: 1, send
permission, chat scope, answers up to 100 KB), which resolves the waiting tool call and
emits a2ui.resolved. Controls are enabled only with the send permission; ordinary
surfaces also need an idle conversation, deferred ones need the capability, and a
question form the user has since replied to stays disabled. User messages that came
from an action render as a "↳ label" line. Shared expectations live in
packages/mobile-contract/surface-fixtures.json; the offline demo's trip conversation
carries a sample surface.
Mobile tool approvals and activity rail
New desktop invitations and desktop approvals default to the Full control preset, which grants every scope. The desktop picker offers presets that map onto ClientPermissions (full: every flag; chat: all_chats, create_chats, send, stop; read: all_chats only) plus Custom for individual flags and per-chat sharing. The presets exist only in the desktop UI; the wire format and stored grants are unchanged, and ClientPermissions still defaults every flag to false for API callers that omit them. Existing grants keep their scope. The permission allows once-only decisions on pending requests, not automatic tool execution or policy editing.
Both native clients use the same activity fixtures in packages/mobile-contract/activity-fixtures.json. They retain text/activity order, group consecutive reasoning and tools into expandable rails, replace replayed arguments, and clear the entire transient state on stream reset. Pending approvals use the desktop queue and show tool arguments with allow/reject actions. All requests in a batch must be decided before the native run resumes; ACP uses its existing live broker. Foreground polling reflects decisions made on desktop.
Navigation and composer
Mobile chat summaries and transcripts include optional platform and
parentChatId metadata. The parent ID is null when it is outside the device's
shared-chat scope. Android and iOS use the same sidebar fixtures to nest and fold
sub-agents in a single layer under the topmost visible parent, retain unshared-parent
conversations as standalone rows, and include the root when searching for a child.
Descendants share one fold control on the main conversation row; child rows never
introduce another folding level. Scheduled conversations and their sub-agents
appear in a separate scheduled-tasks section.
GET /mobile/client/session advertises scheduled_tasks: 1 when
GET /mobile/client/scheduled-tasks is available. Clients skip that request on
older backends. Heartbeat rows (source="heartbeat") are excluded, as on the
desktop, and only tasks whose target conversation is permitted for the device are
included, covering bound tasks and isolated cron-{id} tasks. Unlike the desktop,
tasks bound to the focal agent's chat stay listed: the desktop hides them because its
Regent card shows them, and a paired device has no such card.
It exposes name, active/running/error flags, offset-qualified run times, an
openable chat ID only when that chat exists, and chatUpdatedAt plus
lastRunFinishedAt (the newest run's finish time) so a client can tell an unresolved
failure from one already answered in the chat; prompts and raw errors stay private.
A failure counts as resolved once the chat was updated after that run finished: it
leaves the failing rank, drops the failure status line, and shows the chat's activity
time instead of the run time, exactly as the desktop automation list does.
Both clients order the section like the desktop: unresolved failures first, then
active tasks, then paused ones, each group by next run (tasks without a next run
last). Rows show the desktop status line (paused, paused · failed, last run failed,
next run, active) with a running marker and the last-run date, and the section shows
the task count badge with a five-row preview followed by View all. Search bypasses
the preview so every match stays reachable. This sidebar is read-only. Pending tasks
remain visible without creating a chat. Heartbeat sessions and Regent's own card stay
desktop-only.
Chats live in a searchable sidebar grouped by desktop Project, with one project
expanded at a time — opening another collapses the previous one, matching the
desktop filterId model. Projects are ordered by recent activity, derived from the
newest chat each one owns because the chat listing already arrives newest first.
Sections run scheduled tasks, pinned chats, projects, then ungrouped conversations,
so the scheduled block sits above pinned chats as it does on the desktop. A New
conversation row sits under the header rule, mirroring the desktop sidebar body, and
projects have no create button of their own. New conversation opens an unsaved
composer; only its first non-empty send creates a stored chat.
The chosen project and model carry into that first message; an unsent composer shows
the seeded default project by the name the backend gives it (Home, from
ChatDatabase.DEFAULT_PROJECT_NAME) rather than a localised label. If sending fails after
creation, retries reuse the created chat and retain the draft. Settings
is pinned to the sidebar and contains Desktop access and foreground Node controls.
iOS keeps the sidebar visible at tablet widths; phones use a drawer. The iOS
drawer stays in an opaque composited layer during its slide-out animation. Foreground
navigation refreshes automatically every ten seconds without a refresh button.
The composer is a compact single row while the keyboard is hidden. With the keyboard visible it grows up to six lines and shows the model selector; Return inserts a newline. A dedicated header action opens New conversation. Sending an accepted message clears its draft and dismisses the keyboard. Failed or uncertain sends retain the draft and are never retried automatically. Switching conversations preserves drafts for the current app session. Native conversations offer the backend-enabled model list, submitted with the next message; ACP conversations keep their desktop model configuration. Both mobile apps remember the last explicit model selection locally for each server address, including across app restarts. New conversations restore that selection if the model is still enabled; existing conversations retain their own configuration. Pending model choices are stored per conversation and restored when switching chats, even before sending a message. Once a fetched conversation confirms the choice, its server configuration takes precedence again. Choosing Conversation default clears the remembered selection. This preference is independent of the desktop preference. The backend reads each conversation's saved model (including the original subagent model when no explicit conversation model exists) for both display and sending. Accepted mobile sends persist the model without replacing other conversation settings.
Completed messages have native footers with copy and timestamps. Assistant footers
also show the recorded per-message model (falling back to the conversation model
for older messages), a sources drawer, and conversation branching when creation
is permitted. The latest user message can be edited and resent, and the latest
turn retried, with both send and conversation-management permission. These actions
require an idle conversation, ask for confirmation, and use the desktop retry
checkpoint behavior through the scoped /mobile/client/message-action endpoint.
Replay is unavailable after an intervening automation turn or when the latest
user message no longer matches the saved checkpoint. Branches include the full
assistant/tool continuation associated with the selected reply, even when its
tool rows are hidden by the mobile presentation.
Replay also requires the checkpoint's recorded completion revision to match the
current conversation revision, so transcript-hidden background turns invalidate
it. Older checkpoints without that marker require a new user turn before mobile
replay becomes available.
Saved credentials reconnect automatically on launch and foreground return. A temporarily unavailable desktop shows a retry screen instead of QR onboarding; revoked credentials require pairing again. User messages align right and size to their content, with smaller chat typography on both platforms.
Update the backend alongside the apps: navigation requires /mobile/client/projects
and project/model metadata on mobile chat responses. Project listings and creation
respect the device's existing chat scope; model selection forwards only an enabled
model, never arbitrary configuration or permission overrides.
Mobile chat and controls use shared typeChat, typeControl, typeSection,
typeSidebarSection, controlHeight and sidebarWidth tokens, plus the chrome
tokens borderWidth/borderWidthHeavy, shadowOffset/shadowOffsetHeavy,
shadowOffsetOverlay, radius and selection-light/selection-dark.
spaceRow (10) is the vertical rhythm of every sidebar row — chat, scheduled
task, and heading spacing all read from it, so the list keeps one cadence.
borderWidthHeavy draws the rules in the sidebar chrome, shadowOffsetOverlay
sits under menus, dialogs and the selector panels, and shadowOffsetHeavy covers
the assistant badge and the model/project selection panels. No shadow offset is
hardcoded in either client. Both
platforms use a centered wordmark between equal-size navigation icons and
outlined search fields. The sidebar follows the desktop treatment: a 3 px rule
under its header and along the drawer edge, 10 pt uppercase tracked section
headings, hairline rules between rows, and a grey fill for the current
conversation instead of a leading selection bar. Header icons, the sidebar's New
conversation row and project headers are plain rows from the shared icon/row
primitives — square, no border or shadow, quiet 8% pressed fill — instead of
Material IconButton, a bare SF Symbol or a bordered card; the desktop sidebar
is equally flat, so per-row borders and shadows would read heavier than the
baseline. Popup menus drop their platform elevation in favour of the shared hard
shadow, and dialogs use a 2 px rule with a ruled uppercase header. Primary
buttons retain the desktop blue, square border and hard shadow. Native keyboard,
selection, model menus and system permission controls retain their platform
behavior; iOS rename and delete confirmations still use system alerts.
Successful connection opens the same unsaved start page as New conversation, with the sidebar closed. The welcome area follows the desktop: a cube mascot, the same localized time-of-day greeting, and a project selector. Changing the project only updates the unsaved composer; there are no prompt starter cards. The first send remains the only action that creates a stored conversation.
The native greeting cube adds a six-second float and perspective sway, with two counter-rotating wireframes on a 24-second cycle. iOS pauses its 30 Hz timeline in the background and honors Reduce Motion; Android uses Compose animation layers and disables animation when system animators are disabled.
Model selection opens a separate selection panel owned by the conversation screen, not by the keyboard-dependent composer row. Opening it clears input focus; closing or selecting a model does not reopen the keyboard. This avoids popup focus changes repeatedly removing and recreating the model menu.
Model and project choices share native Suzent selection panels: black title bars, square outlines, hard shadows, yellow selected rows and explicit checkmarks. Long lists scroll, and dismissal leaves the current selection unchanged.
Pairing the same phone again
Use Settings → Pair again, without first forgetting the connection. With an updated backend, the phone proves possession of its saved credential. An unchanged scope and address reuse the token; changed permissions or a LAN/Tailscale address change rotate it while preserving the desktop device entry. The previous token is retired after the replacement is saved securely. Failed or interrupted rotation retains recovery credentials and can resume on reconnect.
Forgetting the connection revokes the device on the desktop when it is reachable, then removes that proof. Phones also send a random per-installation ID on claim; the desktop stores only its hash. A new grant for a known installation keeps the old device ID and stays provisional until the phone confirms it, which retires the stale grant. The ID survives forgetting the connection (Android app storage; iOS keychain, this device only), but not clearing Android app data. Device names are never used to match phones.
Mobile versions and CI builds
Mobile versions are independent of the desktop/backend product version. Add a
mobile impact declaration under .releases/changes/ in feature PRs. The
release/mobile plan updates packages/mobile-contract/version.json and generates
Android's version.properties and iOS's Config/Version.xcconfig; do not bump these
files manually in feature PRs. See the release guide. Both platforms share the
marketing version; the source build number is used for local builds. The desktop
scripts/bump_version.py deliberately does not include these files. Protocol
compatibility continues to use the pairing protocol and capabilities, not matching
product version strings.
The Native mobile workflow runs for relevant pull request updates, relevant
pushes to main, and manual Run workflow requests. It first checks generated
version settings, then assigns both platforms build number 1000 + github.run_number.
This increases with each new workflow run; retries keep the same build number.
CI overrides generated settings only in its checkout, without committing them.
Keep local builds below 1001; reinstalling a lower-numbered local build over a CI
build may require an explicit development downgrade. Preserve this numbering
sequence for debug previews. Signed releases use their own stable range described
in Mobile release distribution.
After Android builds and unit tests pass, download
suzent-android-<version>-<build>-debug from the workflow run's Artifacts section.
Unzip it to obtain app-debug.apk. Artifacts are retained for 30 days and include
PR builds as well as main/manual builds; prefer a successful main build for testing.
These APKs are debug-signed using the runner's temporary development key. They are
not stable upgrade packages: their signature can differ from local installations
and other CI runs. Uninstalling an existing installation to resolve a signature
conflict removes its local connection credentials and requires pairing again.
A fixed signing key is required before distributing upgradeable releases.
iOS PR CI builds the simulator target without signing. The separate Release
mobile workflow builds signed Android APK/AAB files and uploads an iOS device
archive to App Store Connect after a release/mobile merge. It requires the
mobile-release environment and signing credentials; see
Mobile release distribution for setup, outputs, build-number
ranges, retry behavior, and acceptance gates. Rolling mobile-preview releases
and automatic Play Store submission remain future work.
Conversation management
Long-press a conversation on iOS or Android to pin/unpin, rename, move it to a shared project, or delete it after confirmation. Pins and metadata are stored on the backend and shared with desktop. The mobile rows use the same yellow pressed feedback, 44-point minimum menu targets, outlined surfaces, and destructive red actions on both platforms.
These actions require the independent manage_chats permission. The Full
control preset includes it; Chat only and Read only do not. Existing
grants keep whatever they had; change it in desktop Settings → Mobile access.
Sending messages and creating chats do not grant management access. Old backend
sessions without this field are treated as not authorized by both native clients.
Moving/deleting a running conversation is rejected; project moves may not affect
descendants outside the device's shared scope. Mobile deletion never cascades to
subagent conversations. Existing credentials remain valid across this upgrade.
Encrypted local pairing
For a local HTTP backend address, Pair phone now creates a separate local HTTPS endpoint automatically. Scan the QR in the native app and confirm the connection. No Tailscale account, domain, or system root-certificate installation is required. If the desktop address field already contains a public HTTPS origin, that address keeps normal system certificate validation instead.
Allow the desktop backend through the local firewall when prompted. The encrypted
mobile listener uses a persisted port distinct from the desktop HTTP port and
runs only after local pairing has been enabled. Keep mobile_tls in the user
configuration directory across upgrades; it contains the private device identity.
Its server certificate renews without requiring new pairing. Saved addresses are
retried on reconnect; .local name resolution can help after an IP change but is
network-dependent. Rescan if none of the saved addresses resolve to the desktop.
A new device identity is never accepted during reconnect. If the desktop's keys were intentionally replaced, scan a fresh QR to authorize it again. Public HTTPS, Tailscale and reverse proxies remain supported as optional connection methods; this local listener does not provide internet traversal or a relay service.
Updating paired-phone permissions
The desktop operator can replace a device's complete permission set with
POST /mobile/devices/{device_id}/permissions and a permissions object matching
ClientPermissions. The route uses the host authorization boundary; a mobile
credential cannot change its own permissions. Invalid payloads return 400 and
unknown devices return 404.
The store persists the replacement atomically before updating in-memory grants.
The existing credential remains valid, and subsequent mobile requests check the
updated scope. The legacy /management route remains available for older
clients and changes only manage_chats.
The desktop editor keeps a local draft until Save. Cancel discards the draft; failed saves leave it available to retry.
Offline demonstration
Both native apps expose Try offline demo as a quiet text button at the bottom of the unpaired connection screen. Once paired, the entry is under Settings → About; it is absent from connection help and the regular chat surface. It is available in release builds to everyone. The pinned welcome conversation identifies scripted responses; Settings provides Reset demo and Exit demo. Existing desktop pairing credentials are retained when entering or leaving the demo, and demo operations never use them.
The regular conversation UI consumes a MobileClient interface. SuzentClient
(iOS) and BackendClient (Android) implement the real transport; DemoClient
implements a local workspace with no network transport. Both platforms bundle the
same English/Chinese fixtures from
packages/SuzentCore/Sources/SuzentCore/Resources/demo.json. Android includes that
directory as an asset source; SwiftPM processes it as a package resource.
The native navigation shows Regent and New conversation as separate entries, then pinned chats, a three-conversation recent preview with View all, and expandable projects. Scheduled tasks are collapsed below the projects; searching reveals matching task rows. Settings is available from the top toolbar.
The bundled English/Chinese demo includes a successful UI review with tool activity, a simulated source timeout, a daily note, a trip plan, an approval example, a welcome chat and Regent. Existing demo workspaces are preserved on upgrade; Reset demo loads the latest examples.
The demo supports scripted streaming, stop, tool approval/rejection, project/model selection, new conversations, pin/rename/move/delete, branching, editing and retry. Trip and tool-approval prompts are offered on the start page; arbitrary input gets a clearly labelled example response. Attachment selection uses the real native pickers, but the local client records only names and MIME types. It neither reads attachment bytes nor uploads or analyses them. No model API key is needed.
Conversation changes are persisted in a separate versioned demo JSON file in app storage. Running turns progress independently of a stream observer while the app is alive, and reconcile on foreground return. An unfinished turn from a terminated process is marked interrupted on reopening. Reset restores the bundled examples. Pairing and foreground Node controls remain real-desktop features and are explained in demo Settings. Example citations have no remotely fetched favicons; opening a source website is an explicit user action requiring internet access.
For review, provide the exact demo entry and scenario steps, disclose all simulated behaviour, and include a physical-device video of real desktop pairing and interaction. This mode provides an accessible demonstration, not a guarantee that stores will waive access to the real connection flow.
Regent
The chat index prepends a platform: "focal" summary for all_chats grants.
Discovery does not create the singleton or start its heartbeat; the existing
chat-detail path initializes it when opened. The optional regent object carries
waiting, unread and lastMessageAt. Ordinary clients can ignore it. Detail
responses omit the hidden system project's navigation metadata.
ClientPermissions.permits_chat requires all_chats for focal-suzent, including
when its ID appears in an explicit chat list. The same guard covers sending,
observing, stopping and approvals. Mobile management, retry/edit/fork and
attachment sends reject Regent. POST /mobile/client/chats/{chat_id}/read resets
the shared unread counter after an authorized read. Discovery itself never marks
messages read.
Both native clients render Regent as a fixed navigation entry and reuse the normal conversation, stream and recovery mechanisms. A collapsible list links to the five most recent authorized direct child conversations. Navigation polling updates status; a background Regent turn discovered in the selected conversation attaches to the existing observer. Read receipts from polling only run while its conversation is visible. The crown/eyes animate while working, the gem pulses when waiting, and new message timestamps trigger a nod. System reduced-motion settings and foreground lifecycle gate animations.
RegentPresentation in Swift and Kotlin transforms normalized tool results into
separate visible bubbles and user reactions. It suppresses quiet heartbeat replies
and in-flight delivery calls while retaining failed/malformed calls for inspection.
The raw history and live buffers remain authoritative. Reactions stop at background
trigger boundaries. Cross-platform delivery cases live in
packages/mobile-contract/regent-fixtures.json.
Native activity presentation
Chat robots follow display timing up to 120 FPS on both platforms. Eight consecutive frames above 80% of the high-refresh budget limit animation to 60 FPS; 240 frames below half the budget allow recovery. Android uses the Compose frame clock and iOS uses CADisplayLink with a bounded newest-frame buffer. Animation computation stays off the UI thread, and settled robots stop updating. Background and reduced-motion behavior is retained.
Swift and Kotlin ActivityPresentation consume persisted run timings, deduplicate
run IDs and sum resumed active durations without including approval waits. Shared
cases live in packages/mobile-contract/activity-timing-fixtures.json. Missing
timing displays Activity instead of a fabricated duration.
ActivityTurn folds completed process content beneath Worked for while preserving
final prose and Regent delivery bubbles. Pending approvals remain visible. Nested
activity rails and tool blocks expose status, formatted input/output, copy actions
and bounded detail scrolling. Tool-category animations and disclosure transitions
respect reduced motion; ongoing icon animations pause in the background. These
are native generic tool renderers, not the complete desktop rich-renderer set.
Starting a new conversation detaches the selected local stream observer only after composer loading succeeds. Generation guards reject stale updates, and no backend stop is sent. Regent and ordinary tasks therefore continue independently.
Paged conversation navigation
The first screen loads 30 recent chats and a separate pinned page. Projects carry server counts and fetch their own first page when expanded; Load more requests another 30. Title search runs on the server across the authorized history, so an older conversation remains discoverable even if it was never loaded on the phone.
The clients use chat_pagination: 1 and the navigation/page/status routes documented
in packages/mobile-contract/README.md. Older servers retain the legacy index
fallback. Foreground polling refreshes loaded summaries in batches of at most 100;
metadata and the short recent page refresh once per minute. Page loads and search
results are guarded against navigation changes and cancellation. Pull to refresh
on iOS or the refresh action on Android restarts from the newest page. Regent,
project counts and pin discovery do not depend on the recent page.
The demo implements the same paging contract locally. Paging, old-title search, independent pins, duplicate merges and access-scoped counts have regression tests.
Voice composer and shared animation
The paired-device /mobile/client/voice WebSocket reuses VoiceBridge and checks
conversation access plus send/stop permissions. Native audio capture and playback
remain in each app's VoiceSession; the server's state and working events and the
microphone level drive the animation.
Desktop and mobile use frontend/src/lib/voice/voiceCubeRenderer.ts and
voiceCubeSim.ts. Run npm run build:mobile-voice in frontend/ after changing
these files. This bundles an offline HTML asset in SuzentCore's resources, which
both apps already package. npm run check:mobile-voice and the frontend test
check that this asset matches the shared source. The mobile views host only the
animation in a transparent WebView. The canvas uses explicit positioning because
a flex-positioned canvas could render pixels without appearing on screen in
Android WebView. The WebView has no audio, remote assets, or native
JavaScript bridge; controls, captions, and permissions remain native. Dark mode
and reduced-motion preferences are passed to the shared renderer.
ComposerAction in each client prioritizes cancel/hang-up during a call, so task
stopping never appears alongside hang-up. Outside calls it shows stop for running
tasks, progress while busy, send for text/attachments, or voice for an empty
composer. Voice setup and permission errors
produce actionable messages instead of a disabled empty-composer button.
Android uses a separate non-pooling transport for mutations and voice handshakes so they do not inherit idle sockets from background polling. Read requests keep their own connection pool and safe retry policy.