M1 PR3: thomas cloud login / whoami / sync / logout

[thomas-supervisor]

Wires the local thomas CLI to the thomas-cloud SaaS. Federated design — Claude Code (or any other agent driving thomas) never holds the SaaS API key directly; it goes through thomas cloud … verbs that own the device token in ~/.thomas/cloud.json.

CLI surface

thomas cloud login [--base-url <url>] [--label <name>]
thomas cloud whoami [--json]
thomas cloud sync [--json]
thomas cloud logout [--json]

login is interactive (no --json) — it prints a verification URL + 8-char user code, then long-polls /v1/devices/poll until the user approves in their browser. The other three speak the JSON envelope (CloudWhoamiData / CloudSyncData / CloudLogoutData).

THOMAS_CLOUD_BASE_URL env override + --base-url flag let you point at a local thomas-cloud (http://localhost:8000) for dev. Default is https://thomas.trustunknown.com.

What's in the box

src/cloud/
  types.ts       wire shapes: DeviceBegin/Poll, CloudIdentity, CloudSnapshot
  identity.ts    r/w ~/.thomas/cloud.json (0600; device token + workspace)
  cache.ts       r/w ~/.thomas/cloud-cache.json (last /v1/sync snapshot)
  client.ts      fetch wrapper: device-token auth, timeouts, error mapping
  device.ts      RFC 8628 begin + poll loop (respects server interval)
  sync.ts        one-shot /v1/sync → snapshot → cache + lastSyncAt

src/commands/cloud/
  login.ts       interactive: print user_code + URL, poll until approved
  logout.ts      local-only: clear cloud.json (server revoke = future PR)
  whoami.ts      local-only: render cloud.json contents
  sync.ts        emit CloudSyncData summary

SKILL.md         "Driving thomas-cloud (optional SaaS)" section

New error codes

E_CLOUD_NOT_LOGGED_IN, E_CLOUD_UNAUTHORIZED, E_CLOUD_UNREACHABLE, E_CLOUD_TIMEOUT — all documented in SKILL.md with remediation.

Tests

5 new tests in tests/cloud.test.ts against an in-process fake cloud server that mirrors the real apps/api endpoints:

• happy path: login → whoami → sync → logout (single-use token, lastSyncAt updates, idempotent logout)
• already-logged-in: second login attempt errors out without re-issuing
• sync without login: E_CLOUD_NOT_LOGGED_IN
• whoami without login: loggedIn: false (exit 0, no error)
• 401 from server: E_CLOUD_UNAUTHORIZED (simulates revoked token)

256 / 256 tests pass, typecheck clean, build 184 KB.

Real-machine E2E

Drove the full flow against a running apps/api (the thomas-cloud repo's PR2):

1. thomas cloud whoami → loggedIn: false ✓
2. thomas cloud login --base-url http://127.0.0.1:8000 → prints user_code, polls
3. curl /v1/devices/_dev/approve (acting as web user via DEV_MODE bypass)
4. login completes → ~/.thomas/cloud.json written with deviceToken + workspaceId ✓
5. thomas cloud sync → empty snapshot stored in cloud-cache.json ✓
6. thomas cloud whoami → lastSyncAt populated ✓
7. thomas cloud logout → wasLoggedIn: true, cloud.json deleted ✓
8. thomas cloud logout (idempotent) → wasLoggedIn: false ✓

Each /v1/sync request carried Authorization: Bearer <token> correctly.

Depends on

• trustunknown/thomas-cloud PR 请问OpenGuardrails-Text-2510是基于Qwen2.5模型的吗 #1 (self-hosted auth + device-approve) — already merged-ready

Out of scope

• Server-side device revocation on logout (DELETE /v1/devices/{id} not yet on the cloud)
• Background sync loop (daemon-side polling for policy/bundle updates) — added once cloud has policy data to push (M2)
• Drain runs.jsonl upward (M3 — needs /v1/runs/batch on the cloud)

🤖 Generated with Claude Code