refactor: isolate app and OS execution

[adamcohenhillel]

What changed

• Added a portable PhoneToolGateway contract between Assistant features and phone-specific execution.
• Moved hidden android.openphone API access behind the OpenPhoneOsToolGateway adapter at the Assistant composition roots.
• Routed runtime execution, confirmations, generated-surface actions, and runtime status through the gateway.
• Added a source-level boundary validator and wired it into scripts/check.sh.
• Documented the current app/OS ownership model and the remaining work before a Play-distributed companion app is possible.

Why

The OS services already owned privileged execution, but portable Assistant packages still imported hidden OpenPhone framework APIs and the concrete framework executor. That made the app/runtime boundary implicit and easy to erode. This PR creates one explicit seam without changing execution policy or moving authority out of system_server.

Impact

• Existing OpenPhone OS behavior is preserved.
• Assistant feature code can now depend on a small capability contract instead of hidden framework types.
• A future Play app can provide a different adapter, while privileged capabilities remain available only in the OS build.
• This is the first boundary step; the current Assistant APK remains privileged and is not yet Play-buildable.

Validation

• ./scripts/check.sh
• git diff --check
• docs typecheck and production build
• Google Cloud Android build of OpenPhoneAssistant from commit 59ba9f6585febec32c62eed423614d41b1a7dfe9
• Installed on the physical Pixel 9a as version 173 / 0.1.137-dev
• ./scripts/verify-tegu-device.sh
• Confirmed openphone_agent, Assistant, and SystemUI are alive; runtime status reports phone_platform: openphone_os; no Assistant/SystemUI crash entries
• Visually verified immersive AI Home and the existing App Space island

Stack

This draft PR is intentionally based on chore/ai-home-plan / #133 so the boundary refactor stays separate from the AI Home implementation. Retarget it to main after #133 merges.

Full trajectory evaluation was not run because no model API key is configured locally; the no-key device and runtime smokes passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openphone-docs	Ready	Preview, Comment	Jul 21, 2026 2:29am