Skip to content

CONTEXT.md

Latest commit

 

History

History
48 lines (37 loc) · 2.56 KB

CONTEXT.md

File metadata and controls

48 lines (37 loc) · 2.56 KB
Raw

Domain Glossary

Canonical vocabulary for Agent Orchestrator. Terms only — no implementation details, no decisions (those live in docs/adr/).

Daemon surfaces

  • Loopback Listener — the daemon's original, always-on HTTP surface bound to 127.0.0.1. Serves the desktop app and CLI. Unauthenticated: safe only because nothing off-box can reach it. Behaviour is unchanged by the mobile work.

  • LAN Listener — a second, network-facing HTTP surface the daemon exposes so a physical phone can reach it. Off by default; exists only while Connect Mobile is enabled. Authenticated (see Connection Password). Serves the app API but not daemon-control routes (shutdown/lifecycle stay Loopback-only).

Mobile connectivity

  • Connect Mobile: the user-facing capability that enables the separate authenticated mobile listener. It normally opens the LAN Listener and can advertise managed remote endpoints when available. When off, no mobile listener exists.

  • Connection Password: the single, rotating secret that authorises a phone on the mobile listener. It is 8-character alphanumeric, generated by the desktop, and stored by the phone in secure storage. The v2 Pairing QR carries the same bearer value as its token in the URI fragment, so the QR or copied link is a secret. Rotating it invalidates every phone using the old value.

  • Pairing QR: a v2 scannable offer containing the desktop hostId, display name and platform, every advertised endpoint (kind, host, port, and secure), and the bearer token. The offer is base64url-encoded in the URI fragment. The phone verifies the host identity, races the endpoints, and stores the winning host. Legacy v1 codes are rejected.

  • Pairing: the act of a phone acquiring a working connection. The phone can scan a v2 Pairing QR, verify the host identity, race its endpoints, and store the desktop, or enter host, port, password, and TLS details manually. Pairing adds or updates a desktop in the phone's host list.

  • Paired Phone: the phone currently authorised against the active Connection Password. Multiple phones can be paired to one desktop. Each installation has its own device identity for push registration and desktop mute/remove controls, while password rotation invalidates all phones using the old value.

  • Lockout — the brute-force guard on the LAN Listener: repeated failed password attempts from a source are throttled (per-source, not global, so a hostile device cannot lock out the real phone). Resets on a successful auth.