Sophon

Glossary

Alphabetical. Cross-references the Concepts page, which goes in slightly more depth.

Agent

The actual program doing the work — a Claude wrapper, a Python script, a shell pipeline, your own LLM call. Lives on your machine. Sophon never sees it; we only see what your bridge forwards.

Approval

Human-in-the-loop pause. The agent pauses and emits an approval_requested event; iOS surfaces an action sheet; the user taps Allow / Allow always / Deny; the decision flows back through the bridge bus as approval.resolved. See Tool calls & approvals.

Bridge

A long-lived process that translates between your agent and SAP. Holds a WebSocket open to wss://api.sophon.at/v1/bridge/ws, listens for session.message updates, POSTs replies through /v1/bridge/*. OpenClaw is the canonical example. Synonymous with connector in everyday usage.

Bridge token

A long-lived secret of the form inst_<id>:s_<env>_<secret>, issued at pairing. Authenticates every /v1/bridge/* call. Stored on the bridge side; lost on revoke.

Bucket

Rate-limit grouping. Routes are bucketed (msg, delta, task, approval, memory, default); each bucket is scoped per (scope, owner_id, bucket). Returned in the X-RateLimit-Bucket header. See Errors & rate limits.

Connector

Synonym for bridge in casual use. Strictly speaking, the "connector" is the runtime + the SAP-translation layer; the "bridge" is the relay process. Most days the distinction doesn't matter.

Connector type

Identifier for the kind of bridge — e.g. openclaw. Sent at pairing time; iOS uses it to pick the right install instructions.

Idempotency key

Opaque string, 1–64 chars [a-zA-Z0-9_-], attached to every mutating request. The pair (token, idempotency_key) is unique within 24 h. Lets your bridge retry safely. See Idempotency & resume.

Installation

One paired bridge on your account. Identified by an installation_id like inst_q9w8e7r6t5y4u3i2. Each pairing creates one installation; you can have many under the same account (work Mac, home Mac, a VPS).

Interaction

One user-message-then-agent-reply cycle inside a session. Identified by interaction_id (int_…). Every event during the cycle (deltas, tool calls, approvals) carries this id so the client can route deltas to the right bubble.

Message

What you see in a bubble. Has a message_id, role (user / agent), text, optional attachments, optional usage metadata. Streams as deltas during an interaction and finalises on message_end.

Pairing

The handshake that issues a bridge token. The bridge calls POST /v1/pairing/start, prints a 7-letter code, polls; the user types the code in iOS Settings; the bridge's next poll returns the token. See Connection lifecycle.

Pairing code

A 7-letter string (e.g. 9FP9SVT) valid for 120 s. Bridge prints it; user types it in iOS to claim.

Resume

Reconnecting to a stream without losing data. Two flavours:

  • SSE resume — iOS sends Last-Event-ID; server replays the ring buffer.
  • Cold-launch snapshot — for gaps older than the buffer, iOS calls GET /v1/me/snapshot?since=<ts> and folds the result into local state.

Ring buffer

Server-side per-user buffer of the last 256 SSE events / 5 minutes, used for Last-Event-ID resume. Gaps older than this require a snapshot fetch.

SAP

Sophon Agent Protocol. The wire format documented on this site; normative spec here.

Session

A chat thread inside one installation. Has a session_id (ses_…), a title, a state (active, archived, soft-deleted). Visible in the iOS chat list.

Session token

The user's authentication on /v1/me/* calls. Owned by iOS, never seen by your bridge.

Snapshot

GET /v1/me/snapshot?since=<ms>. Returns every session, message, task, and approval that changed since the timestamp. Used by iOS on cold launch when the gap exceeds the SSE ring buffer. See Streaming model.

SSE

Server-Sent Events. The transport iOS uses to receive updates from the cloud — GET /v1/me/stream.

Task

Internal name for a tool call. The lifecycle is created → progress* → completed | failed | cancelled. Has a task_id. Renders as a card in the agent bubble. See Tool calls & approvals.

Tool call

A single tool invocation by the agent. Same thing as a task; "tool call" is the user-facing word, "task" is the wire-format word.

traceparent

W3C Trace Context header. <version>-<trace_id>-<parent_id>-<flags>. Returned on every /v1/* response. See Observability.

Update

A frame the server pushes to your bridge over WebSocket. Has an update_id (monotonic per-installation) and a type (session.message, approval.resolved, …). Dedupe by update_id — at-least-once delivery.

update_id

Monotonic per-installation integer, used for deduping. Send { "type": "ack", "up_to_update_id": "12" } to confirm receipt.

WebSocket

The transport between your bridge and the cloud — wss://api.sophon.at/v1/bridge/ws. Auth via Authorization: Bearer inst_… header on the upgrade.

X-Request-ID

Per-HTTP-exchange correlation header. Format req_<16 lowercase hex> when server-generated; clients may supply their own. Log it on every error. See Observability.