54 行
1.6 KiB
Markdown
54 行
1.6 KiB
Markdown
# Desktop Gateway v1 HTTP and SSE surface
|
|
|
|
## Public discovery
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
system.heartbeat
|
|
message.delta
|
|
message.completed
|
|
message.proactive
|
|
agent.status
|
|
tool.proposal
|
|
capabilities.changed
|
|
error
|
|
```
|
|
|
|
## Local action reporting
|
|
|
|
```text
|
|
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.
|