Sophon

Connector checklist

Use this page when you already have an agent runtime and want to make it feel native inside Sophon. It is intentionally implementation-focused: what to build, what to test, and what iOS expects to see.

1. Decide what you are wrapping

A Sophon connector is not the agent. It is the relay between Sophon Cloud and an agent you already run.

Good connector targets:

  • A local OpenClaw or Claude Code-style runtime.
  • A long-running Python or TypeScript service.
  • A CLI you can spawn per turn.
  • An MCP-backed tool runtime.
  • A hosted agent API you control.

Avoid putting agent design, prompting, or model orchestration into the Sophon layer unless your runtime has nowhere else for it to live.

2. Pair once, then store the token

Your connector needs one bridge token per installation.

Checklist:

  • Start pairing with /v1/pairing/start.
  • Show the short code or open the browser confirmation flow.
  • Poll /v1/pairing/poll until paired.
  • Store the returned inst_…:s_live_… token locally.
  • Never put the token in a URL, log line, crash report, or checked-in config.
  • Provide a way to rotate or delete the local token.

3. Hold the WebSocket open

Connect to:

wss://api.sophon.at/v1/bridge/ws
Authorization: Bearer inst_…:s_live_…

Checklist:

  • Wait for { "type": "ready" } before accepting work.
  • Respond to ping frames with pong within 10 seconds.
  • Reconnect with exponential backoff.
  • Acknowledge processed updates with ack.
  • Treat duplicate updates as normal. Reconnect replay is part of the contract.

4. Handle user messages

The update you care about first is session.message.

Checklist:

  • Parse session_id, interaction_id, and user message text.
  • Translate the message into your runtime's input format.
  • Keep a per-interaction queue so placeholder, deltas, tools, and finalization arrive in order.
  • Preserve attachments if your runtime supports them. If not, fail clearly.

5. Open the agent bubble early

Before a long model call, create the agent bubble:

POST /v1/bridge/sendMessage

Checklist:

  • Include session_id.
  • Reuse the interaction_id from the user message when present.
  • Send a placeholder/empty text if the answer will stream.
  • Store the returned message_id for deltas and finalization.

This is what lets iOS show a native “thinking” state immediately.

6. Stream, then finalize

Checklist:

  • Send text chunks through /v1/bridge/sendMessageDelta.
  • Rate-limit your own delta bursts.
  • Always call /v1/bridge/sendMessageEnd when the turn is done.
  • Include final canonical text if your runtime has it.
  • Include usage metadata when available: model, provider, token counts, cost.

If the runtime fails, finalize the bubble with a useful error message rather than leaving the UI stuck in a streaming state.

7. Forward tool calls as tasks

If your runtime runs tools, mirror them as task_* events.

Checklist:

  • createTask when a tool starts.
  • updateTask for meaningful progress.
  • finishTask with completed, failed, or cancelled.
  • Use a stable task_id, ideally the provider's native tool-call id.
  • Include readable status_label, args, result, and error when available.

Sophon renders these as native tool cards and persists them in the chat history.

8. Pause for approvals

For risky actions, ask the user first:

POST /v1/bridge/requestApproval

Checklist:

  • Include a stable approval_id.
  • Make title, message, and command human-readable.
  • Set severity honestly. Do not mark destructive commands as low risk.
  • Listen for approval.resolved on the bridge WebSocket.
  • Map decisions into your runtime's vocabulary: allow once, allow always, deny.
  • Handle expiry as a denial unless your runtime has a safer fallback.

9. Make retries safe

Checklist:

  • Use idempotency_key on bridge POSTs where available.
  • Retry 5xx and network errors with backoff.
  • Respect 429 and Retry-After.
  • Do not retry user-visible side effects blindly unless the route is idempotent.
  • Treat message_id, task_id, and approval_id as natural dedupe keys.

10. Test the real user experience

Before calling a connector done, verify these flows in iOS:

  • First pairing.
  • First message.
  • Streaming text.
  • Tool card creation and completion.
  • Approval request, approve, approve always, deny.
  • Kill the app mid-stream, reopen, and confirm history reconstructs.
  • Disconnect the connector, reconnect, and confirm updates resume.
  • Rotate or delete the token.

Read next