Mobile AI Bridge

Mobile AI Bridge Architecture

Status: implementation contract for CAS-2098 / CAS-2105 Child E.

Overview

The Mobile AI Bridge connects iOS clients to the local macOS AI daemon through a Cloudflare Worker.

Request path:

1. iOS app sends HTTPS request to https://ai-bridge.casaconomy.com/v1/chat.
2. Worker authenticates bearer token and forwards to the paired daemon tunnel.
3. Daemon dispatches the command and returns JSON response.
4. Worker streams/forwards response back to iOS.

Pairing path:

1. macOS daemon creates short-lived pairing session (token, pin, expires in 5 minutes).
2. iOS calls POST /v1/pair/confirm with {"pin":"NNNNNN"}.
3. Successful response returns:

• token (bearer secret)
• server_public_key (daemon X25519 public key; 32 bytes)
• worker_url (bridge base URL for future calls)

Command Envelope Schema

All bridge calls use a versioned command envelope.

{
  "command": "ai_chat",
  "version": 1,
  "payload": {
    "conversation_id": "uuid-or-client-id",
    "message": "user prompt"
  }
}

Rules:

• command: required string command identifier.
• version: required integer protocol version.
• payload: required object, shape depends on command.

Dispatcher Pattern And Extension Model

Daemon-side request handling uses a command dispatcher.

Pattern:

1. Parse envelope.
2. Match on command.
3. Route to handler for that command.
4. Return normalized success/error envelope.

Extension model for new commands:

1. Add a new dispatcher match arm for the command name.
2. Implement the handler with explicit payload validation.
3. Add compatibility tests (known command and unknown command).
4. Ship without changing existing command contracts.

This preserves forward compatibility and prevents ad-hoc endpoint growth.

Unknown Command Semantics

If command is not recognized, daemon returns HTTP 400 with:

{
  "error": "unknown_command",
  "command": "future_command_that_doesnt_exist",
  "supported": ["ai_chat"]
}

Client handling contract (iOS):

• Show an informative error banner.
• Do not crash.
• Do not hang/spin indefinitely.
• Allow immediate retry with a supported command path.

Security Model

• Pairing returns bearer token and daemon public key over TLS.
• iOS stores token and server key in Keychain.
• Worker authenticates bearer token before forwarding.
• Worker and daemon logs must not include prompt body or secret tokens.

End-To-End Verification Checklist (Child E)

• Pairing flow completes in <60s with no terminal commands on iPhone. (regent confirmed 2026-05-10)
• Both Keychain items populated after pairing. (regent confirmed 2026-05-10)
• End-to-end: iPhone prompt -> streaming response from claude CLI on Mac. (regent confirmed 2026-05-10)
• Mac offline -> 503 -> immediate banner (no spinner hang). (handled by CAS-2281 unified ReportSheet)
• Worker log verification (wrangler tail) shows no prompt body. (deferred — traffic currently bypasses Worker via cloudflared; re-verify after CAS-2198 puts Worker in path; tracked in CAS-2340)
• Re-pair flow clears and replaces Keychain items correctly.
• Regression: send command: "future_command_that_doesnt_exist" through full stack -> daemon returns 400 unknown_command payload -> iOS shows informative banner (no crash/hang). (deferred to CAS-2340)

Troubleshooting

Pairing fails with timeout: Ensure the daemon is running (casaconomy-ai-bridge start) and the cloudflared tunnel is active before entering the PIN on iOS. The PIN expires in 5 minutes.

Bearer token rejected: Re-pair. The token is bound to the daemon instance that issued it; a daemon restart generates a new key pair.

Banner not appearing when Mac is offline: The CloudBridge provider returns 503 with bridge_offline; the ReportSheet (CAS-2281) renders the banner on that code. Ensure the app version includes CAS-2281.

What changed {#what-changed}

This chapter was introduced in CAS-3637 Phase 3 (The Casaconomy Book) as the canonical reference for the Mobile AI Bridge.

See: CHANGELOG → 2026-05-18