Skip to content

copper-cloud 0.13.0: device agent relay - #9

Merged
astherath merged 1 commit into
mainfrom
feat/device-agent
Oct 31, 2026
Merged

astherath merged 1 commit into
mainfrom
feat/device-agent

Conversation

@astherath

Copy link
Copy Markdown
Contributor

Agents (any MCP client) can use a person's Copper for iOS through the cloud. The phone dials out and holds an SSE mailbox while Copper is on screen; the agent calls POST /v1/agent/mcp with a cat_ token the phone minted. Feature flag in /v1/info: device_agent.

Device side (gate + session): POST/GET /v1/me/links, GET/DELETE /v1/me/links/{id}, GET/POST /v1/me/links/{id}/frames (SSE mailbox; uploads up to 32 MiB), POST/GET /v1/me/agent-tokens, DELETE /v1/me/agent-tokens/{id}.

Agent side (outside the instance gate — exactly /v1/agent and /v1/agent/…; /v1/agents/* other than the existing pair route stays gated): GET /v1/agent/status, POST /v1/agent/mcp (MCP Streamable HTTP, stateless; JSON or SSE answers with 10 s keepalives and progress notifications; cancel to the device on the 200 s deadline, agent disconnect, revoke or shutdown; immediate answer when the phone is offline). 600 req/min per token.

  • Tokens: cat_ + 256 random bits, only SHA-256 stored, bound to user + device, revocable; deleting a device revokes its link and tokens.
  • In-memory hub for streams / calls in flight; links and token hashes in migration 0016_device_agent.
  • One audit line per call (token id, device id, tool, ms, status), never arguments or results; new metrics device_agent_streams, device_agent_calls_total{status}, agent_rate_limited_total.
  • Docs: docs/api.md#device-agent-relay, architecture, security, operations, new CHANGELOG.md, docs/v0.13.0.md (with the rollback to 0.12.x: 0.12.x refuses to start with 0016 applied unless run with --no-migrate or the migration is removed).

Validation: cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, cargo test --workspace against native PostgreSQL — 249 passed, 0 failed (17 new relay integration tests: gate exemption, ownership 403/404, token mint/list/revoke, rate limit, MCP basics, JSON + SSE relay with progress, deadline/disconnect/revoke/device-delete cancellation, 32 MiB frames, offline detection, log hygiene).

…agent tokens, MCP at /v1/agent/mcp)

An agent (any MCP client) drives a person's Copper for iOS through the cloud: the phone
registers a link with its tool manifest and holds an SSE mailbox while Copper is on screen;
the agent calls POST /v1/agent/mcp with a cat_ token the phone minted.

- Device side (gate + session): POST/GET /v1/me/links, GET/DELETE /v1/me/links/{id},
  GET/POST /v1/me/links/{id}/frames (SSE mailbox; 32 MiB upload), POST/GET
  /v1/me/agent-tokens, DELETE /v1/me/agent-tokens/{id}.
- Agent side (outside the gate, exactly /v1/agent and /v1/agent/...): GET /v1/agent/status,
  POST /v1/agent/mcp (MCP Streamable HTTP, stateless; JSON or SSE with 10 s keepalives and
  progress notifications; cancel to the device on deadline, disconnect, revoke).
- In-memory hub (streams, pending calls, per-token limiter); links + token hashes in
  migration 0016. Deleting a device revokes its link and tokens.
- Metrics device_agent_streams / device_agent_calls_total / agent_rate_limited_total; one
  audit line per call, never arguments or results.
- Docs: api.md section, architecture, security, operations, CHANGELOG.md, docs/v0.13.0.md
  (incl. rollback to 0.12.x).
@astherath
astherath merged commit 72b5e87 into main Oct 31, 2026
2 checks passed
@astherath
astherath deleted the feat/device-agent branch October 31, 2026 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant