Device Diagnostics

# Device Diagnostics

When a Device misbehaves, start from two server-side facts: its canonical state,
and the developer-safe logs of the Project Environment it belongs to. Both come
from the Control API, and the Device itself is never queried. The same steps work
from your own server and from an AI client through the [MCP Guide](MCP_GUIDE.md).

## What you need

- The Device id (`dev_…`), its Project id and its Environment id.
- An access token for your account with the `device.read` and `logs.read`
  Grants in that Project Environment.

## Read the Device's canonical state

`GET /v1/devices/{device_id}` returns the Device as OneSay knows it. The Control
API, not the Device, is the source of this state: a Device that cannot reach
OneSay still has its last recorded state here.

## Search the developer-safe logs

`GET /v1/logs?project_id=…&environment_id=…` lists the Project Environment's
developer-safe logs, a page at a time: pass `next_cursor` back as `cursor` while
`has_more` is true. An entry has an event, a severity, a time, a latency, the
ids of the resources it concerns (look for your `device_id` there) and safe
fields such as an `error_code`. It never carries audio, a transcript or a
credential.

Each entry names its `request_id` (`req_…`). `GET /v1/logs/{request_id}`
returns that request's timeline, which shows where a failing call stopped.

## With an AI client

- `onesay.devices.diagnose` takes `device_id`, `project_id` and
  `environment_id` (and optionally `cursor` and `limit`). It returns one object
  with the Device's canonical state under `getDevice` and one page of logs
  under `listDeveloperLogs`.
- `onesay.logs.timeline` takes a `request_id` from those logs.
- The `diagnose_device` prompt walks a client through these steps, using this
  page.

Both tools are R1: they need a token and change nothing.

## What these steps do not cover

Board hardware, firmware and radio quality are diagnosed by the device's OS and
board vendor, not by the Platform. A Device's own local logs never reach OneSay
unless the device runtime sends them.