1.6 KiB
Desktop Gateway v1 HTTP and SSE surface
Public discovery
GET /desktop/v1/health
GET /desktop/v1/server-info
GET /desktop/v1/capabilities
server-info.serverInstanceId becomes the expected server identity for the active connection. A later mismatch freezes that connection rather than silently rebinding it.
Authentication
POST /desktop/v1/auth/login
POST /desktop/v1/auth/refresh
Credentials and returned tokens remain in the Rust layer. Request and response bodies containing credential material must not derive or use unrestricted debug logging.
Messaging and events
POST /desktop/v1/messages
GET /desktop/v1/events/stream
POST /desktop/v1/events/{event_id}/ack
SSE frames carry both the SSE id and the complete JSON event envelope in data. Reconnect uses the Last-Event-ID request header. Replay and de-duplication are scoped to the local connection profile, so the same event ID on two server instances remains two distinct events.
Initial event types:
system.heartbeat
message.delta
message.completed
message.proactive
agent.status
tool.proposal
capabilities.changed
error
Local action reporting
POST /desktop/v1/local-actions/{action_id}/accepted
POST /desktop/v1/local-actions/{action_id}/rejected
POST /desktop/v1/local-actions/{action_id}/progress
POST /desktop/v1/local-actions/{action_id}/result
A tool.proposal is only an untrusted proposal. Schema validation, tool registry validation, slot/profile checks, server identity verification, expiry checks, local policy, and user authorization happen before any local execution.