Design remote agent API and Atem trust handoff

[guohai]

Remote clients currently need a running Mac and Astation's protected local API. This design starts the remote API for mobile Astation, other independent native clients, and scoped services/bots to reach original Atem-launched agents whether the Mac is online or offline.

Mac and mobile can use the same original sessions simultaneously through independently authenticated connections. Document one terminal control lease per agent session, atomic prompt Send and confirmed expected-controller takeover, lease-free approval answers/revocation that preserve another device's lease, and independent sleep/wake/reconnect behavior.

Use WSS initially, with transport adapters allowing a later Agora Signaling integration after runtime/network and shared-protocol verification. Whole-message updates are sufficient; token-by-token streaming is not required.

Approval cards/live events are immediate. Still-pending approvals get an initial push at 60 seconds and a reminder at 180 seconds. Each client registers its first-alert-stage preference: desktop defaults to both stages, mobile to the reminder only. The relay suppresses mobile's initial OS push before submission, since client filtering alone cannot reliably hide an OS-rendered notification while suspended. No trusted desktop/mobile category is needed; desktop receiving the reminder is intentional. Both deadlines are independent of desktop availability. Separate live-card dedup from per-stage OS delivery. Signed creation time, resolution cancellation, expiry, recovery and provider races are covered by the Atem handoff and headless test matrix. Authenticated ingress, notification preferences and scheduling remain proposed, not enabled; PC OS delivery needs its platform adapter.

Require rich mobile/native chat using the existing Markdown text and typed tool/approval parts. Preserve paragraphs, headings, emphasis, links, lists, code and tables through live/history/API delivery, with mobile layout/accessibility and inert-content rendering. No new host message type is needed for basic formatting; images/files remain separate capabilities. Add source-fidelity and platform renderer checks to the verification plan.

Document high-level client operations, proposed encrypted relay transport, independent principals and delegation, end-to-end authority, r8 receipts/history, recovery, and a headless verification matrix covering concurrent devices as well as Mac-off operation. The relay transports records and cannot grant agent access through account login.

The Atem implementation handoff asks for four joint decisions first: freshness/fork handling, principal types and wire versioning, signed formats/secure channel, and ownership of a reusable client core. The existing #70 manager-nonce construction does not establish its claimed revocation bound; this draft retains section 9's gate and does not silently weaken it. New remote routes are proposed, not enabled. No Atem checkout was changed or built.

Atem coordination handoff: Agora-Build/Atem#81 records the latest product requirements and requested host/security decisions.

Baseline: Astation main 4f4581a (#56), agreed r8 application contract Atem 4f87bab (#78), and read-only review of latest Atem main 0801a4f. Known non-critical local client follow-ups remain tracked separately in #57.

Validation: all 14 relative Markdown links across the three documents resolve, the remote and push designs are ASCII, and git diff --check passes. Documentation only; runtime tests were not required and no new live-provider tests are claimed.

Generated with SMT smt@agora.build