@thalovant/mcp-server 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.6.0 — 2026-09-28
+
+Link Home Assistant, or any home controller, to a hub from an agent: sign in on the device, create a connection of the `home_assistant` kind, and wait for the hub to admit it. Existing tool schemas are unchanged; every addition is optional.
+
+- **Device sign-in as two tools.** `thalovant_begin_device_login` answers the code and URL to show a person with an opaque `loginId` (an empty `scopes` list is accepted and left out, so the API's default applies); `thalovant_poll_device_login` asks once and answers `pending` (with the interval, lengthened for good after a `slow_down`), `approved`, `expired` or `denied`. The device code and the minted token stay on the server, bound to the principal that began the sign-in, and never reach the model. With no credential configured, every control-plane tool for that principal then uses the token. `thalovant_revoke_device_login` signs out; a token already revoked counts as revoked, and signing out again answers `alreadyRevoked` without asking the API. A sign-in reaches only the configured API origin, because its verification URL is shown to a person.
+- **Connections of a kind.** `thalovant_create_client_identity` takes `connectionType`; the API must answer with the same kind, and a connection it made without it is deleted again before the call fails. The result carries `clientId`, `connectionType` and `operationId`. A refusal adds guidance by kind after the API's own text: a kind the API does not know yet, a plan that does not allow it, a hub already linked (naming the connection that holds the link), or a token to sign in again.
+- **Admission.** `thalovant_wait_for_admission` (read-only) follows the create's operation for the ninety seconds a hub takes and answers `admitted`; `failed`, with the operation's `errorCode` for a failure on the platform or the API's `status`, `code` and `detail` when it refused the wait itself; or `timeout` as an outcome to wait on again. A 429 is ridden out for the time the API names (its body, else `Retry-After`, else `RateLimit-Reset`), and one asking for longer than is left is a timeout at once. A token the API refuses and an API out of reach are tool errors of their own, each with a hint. It honours MCP cancellation and never follows a link to another origin than the API's.
+- **`thalovant_delete_client`**, opt-in with the other destructive tools: `If-Match`, reading the etag first when none is given, one retry on `412`, and a connection already gone counts as deleted.
+- The catalog has 50 default tools (24 in read-only mode, 53 with destructive tools enabled). `thalovant_config_status` reports `deviceLoginSignedIn`.
+- Takes `@thalovant/sdk` ^0.9.0, which carries the device sign-in, the connection kinds and admission; the lock resolves 0.9.0.
+- The parity contract declares `device-login`, `connection-kinds` and `connection-admission` as required and `home-link` as not applicable: a tool call holds a hub connection only for its own length, and nothing could answer a hub's request. The three vector files run through the SDK that resolves here, recorded before asserting, and through the tools over stdio, recorded under the same names; all 46 cases digest as the reference's (reference `2460eb90bd56`). Each worker of the recorder now writes only a shard of its own, and a Vitest global setup (`vitest.config.ts`) merges the shards once after every worker has finished: merging inside the workers let two of them stage the same file and rename each other's away, and a merge that scanned early could land after a complete one.
+- The Dockerfile's version label had stayed at 0.4.0; it now says 0.6.0 like the rest.
+
+## 0.5.3 — 2026-09-26
+
+- A tool error says what the API said, not only the SDK's one-line message. That line is cut at 160 characters, and a `platform_image_required` refusal names every image each refused key may be instead -- longer than that -- so the list a model needed to retry was the part cut off, and `refused_images`, `allowed_images` and `allowed_repositories` never reached it at all. The error text now goes on with `code:`, `detail:` (the whole sentence, when the first line had to shorten it) and `fields:`, every other member of the body as compact, redacted JSON. A value a validation error echoes back from the request is redacted there and never reaches the first line.
+- A `platform_image_required` or `plan_limit` 403 gets a hint that fits it instead of the general "Insufficient scopes" hint: granting a scope changes neither.
+- The status behind a hint is read from the SDK error's `statusCode`, not parsed out of its message.
+- Take `@thalovant/sdk` ^0.8.7, whose `ThalovantApiError` carries `code`, `detail` and `problem`. The shared `api-error-vectors.json` run here twice: through the SDK that resolves, recorded before it is asserted, and through a real tool call against the built server.
+- New `api-errors` capability in the parity contract, declared `required`.
+
 ## 0.5.2 — 2026-09-19
 
 - Take `@thalovant/sdk` ^0.8.2, which ends an ask the hub refuses at once as a typed refusal rather than waiting out its deadline and reporting that the hub did not answer in time. This server implements no part of an ask, so the behaviour arrives with the dependency -- and the shared refusal vectors now run here, against whatever version actually resolves, beside the conversation carry, the hive kinds and the binary frames.

package/README.md

@@ -43,6 +43,17 @@ The server selects control-plane auth in this order:
 
 When a token is set, the server never calls the login endpoint. `thalovant_config_status` reports the active mode as `controlPlaneAuthMode` without revealing token values.
 
+With none of these configured, a person can sign the server in through the browser instead: see [Device Sign-In](#device-sign-in). The token that sign-in mints is used only when nothing above is configured.
+
+### Device Sign-In
+
+A tool call cannot wait for a person, so the device flow (RFC 8628) is two tools:
+
+1. `thalovant_begin_device_login` with optional `scopes` (an empty list, like none, asks for the API's default) and `clientName` answers `loginId`, `userCode`, `verificationUri`, `verificationUriComplete`, `interval` and `expiresIn`. Show the person the URL and the code.
+2. `thalovant_poll_device_login` with that `loginId` asks once. `outcome` is `pending` (poll again after `interval` seconds, already five seconds longer for good if the API asked to slow down), `approved` (with `tokenId`, `scopes` and `expiresAt`), `expired` or `denied`.
+
+The device code and the token never reach the model: the server keeps both, bound to the principal that began the sign-in, for the life of the process. Once approved, every control-plane tool for that principal uses the token when no credential is configured. `thalovant_revoke_device_login` signs out: it revokes that token (a token may always revoke itself, and one already revoked counts as revoked) and forgets it; signing out again answers `alreadyRevoked` without a request, and configured tokens are never touched. A sign-in reaches only the configured API origin (`THALOVANT_API_URL`, or the default), since the verification URL it answers with is shown to a person. A Home Assistant link asks for `hubs:read`, `clients:read` and `clients:write`, which is also all a Free plan can approve.
+
 ### API Tokens (Recommended For AI Agents And CI)
 
 Scoped API tokens are the right credential for AI and automation use: they are minted from the Thalovant dashboard (or through the device flow), carry only the scopes you grant, can be revoked individually, and never involve your account password or MFA. Tokens start with `tvpat_`.
@@ -61,7 +72,7 @@ Minimum scopes for the full control-plane tool surface:
 | `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, `thalovant_list_marketplace_skills`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, the guarded merge read in `thalovant_update_runtime_group_config`, and the hub lookup inside `thalovant_create_client_identity` |
 | `hubs:inspect` | `thalovant_get_hub_runtime_capabilities`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory`, `thalovant_list_hub_skills`, `thalovant_list_hub_skill_history` |
 | `hubs:write` | All hub and runtime-group provisioning: `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_create_runtime_group`, `thalovant_update_runtime_group`, `thalovant_update_runtime_group_config`, `thalovant_release_runtime_group`, `thalovant_install_runtime_group_skill`, `thalovant_uninstall_runtime_group_skill`, the per-hub `thalovant_install_hub_skill`, `thalovant_update_hub_skill`, `thalovant_remove_hub_skill`, the hub rating tools, and the opt-in delete tools |
-| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
+| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) and the opt-in `thalovant_delete_client` |
 | `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |
 | `memory:write` | `thalovant_create_memory_item`, `thalovant_update_memory_item`, `thalovant_delete_memory_item` |
 
@@ -87,7 +98,7 @@ Grant fewer scopes for narrower deployments: a read-only assistant needs only `h
 
 `thalovant_list_hub_skills` returns the whole `GET /v1/hubs/{hub_id}/skills` envelope: `hub_id`, `runtime_group_id`, `observed_at`, `source`, the runtime's phase and message, and `data`, one row per skill (possibly empty) with `skill`, `title`, `marketplace_skill_id`, `package_name`, `source_type`, `install_source`, `version`, `version_pin`, `installed_version`, `observed_version`, `previous_version`, `latest_version`, `available_version`, `update_available`, `changelog`, `active`, `state`, the runtime's phase, message and last error, and `last_transition_at`. `state` is one of `pending`, `installed`, `failed`, `removing`, `drifted`, `quarantined`, or `unmanaged`; a change in progress shows as `pending`.
 
-Each write answers `202` with `operation_id`, `hub_id`, `runtime_group_id`, `skill`, `version` (`null` for a removal), `previous_version`, and `state` (`installing`, `updating`, or `removing`); pass `wait: true` to poll that operation every 2 s until it converges (`installed`, or `removed` for a removal; a `failed` or `timed_out` operation raises an error carrying its `error_message`), with a 120 s default `timeoutMs`, or follow it yourself with `thalovant_get_operation`. Installing a skill that is already installed at another version performs an update; the same version fails `409` with code `skill_version_already_installed`. A hub with no runtime group fails `404` with code `hub_without_runtime_group` (a plain `404` means an unknown hub or a skill that is not installed), and an unresolvable `latest` or an invalid version fails `422`. Errors are RFC 7807 problem bodies; the tool error keeps the short `message` and appends the root `code` in parentheses, for example `Thalovant API request failed with HTTP 409: Skill version already installed. (skill_version_already_installed)`.
+Each write answers `202` with `operation_id`, `hub_id`, `runtime_group_id`, `skill`, `version` (`null` for a removal), `previous_version`, and `state` (`installing`, `updating`, or `removing`); pass `wait: true` to poll that operation every 2 s until it converges (`installed`, or `removed` for a removal; a `failed` or `timed_out` operation raises an error carrying its `error_message`), with a 120 s default `timeoutMs`, or follow it yourself with `thalovant_get_operation`. Installing a skill that is already installed at another version performs an update; the same version fails `409` with code `skill_version_already_installed`. A hub with no runtime group fails `404` with code `hub_without_runtime_group` (a plain `404` means an unknown hub or a skill that is not installed), and an unresolvable `latest` or an invalid version fails `422`. Errors are RFC 7807 problem bodies; the tool error keeps the short `message`, which appends the root `code` in parentheses, for example `Thalovant API request failed with HTTP 409: Skill version already installed. (skill_version_already_installed)`, and then the code and the body's other fields (see [Tool Errors](#tool-errors)).
 
 Listing needs `hubs:inspect` (implied by `hubs:read`); the writes need `hubs:write` and a paid plan, and because scope is checked before plan a free-plan token sees `403`, never `402`. Hub-restricted tokens (a `hub_ids` allowlist) are honoured on all four routes. The server uses the published Node SDK hub-skill methods and preserves MCP cancellation checks during polling. A failed status read retains the accepted operation ID; use `thalovant_get_operation` with that ID instead of submitting the write again. No new poll starts at or after the polling deadline. That deadline does not cancel an HTTP request already in flight.
 
@@ -112,6 +123,18 @@ URL spellings and paths on the same origin are allowed; custom origins must be
 configured alongside their credentials. Anonymous public discovery may still
 select a custom API URL.
 
+## Link Home Assistant
+
+A home controller such as Home Assistant links to a hub with a connection of its own kind:
+
+1. Sign in, when no token is configured: [Device Sign-In](#device-sign-in).
+2. `thalovant_create_client_identity` with `connectionType: "home_assistant"`. The API must answer with the same kind; one that made an ordinary connection instead has it deleted again and the call fails. The result carries `clientId`, `connectionType` and `operationId`.
+3. `thalovant_wait_for_admission` with that `operationId`. A hub admits a new connection in about ninety seconds and refuses it until then. `outcome` is `admitted`, `failed` or `timeout`. A failure on the platform carries the operation's `errorCode` (and `status` null); the API refusing the wait itself carries its `status`, `code` and `detail`. A `timeout` means the connection may still be admitted: call the tool again rather than creating another connection. A 429 is waited out for the time the API names (in its body, else `Retry-After`, else `RateLimit-Reset`); one asking for longer than is left is a `timeout` at once. A token the API refuses (401, 403) and an API out of reach are tool errors of their own, each with a hint, never a failed admission. It reads only, honours cancellation, and never follows a `links.self` to another origin than the API's.
+
+Each refusal of step 2 names what to do next after the API's own text (see [Tool Errors](#tool-errors)): a kind the API does not know yet, a plan that does not allow the connection, a hub that already holds its one Home Assistant link (with the `client_id` holding it), or a token the API refused (sign in again). `thalovant_delete_client` removes a connection (`If-Match`, reading the etag first when none is given, retrying once on `412`, and counting a connection already gone as deleted); it is a destructive tool the operator enables.
+
+Answering the hub's requests afterwards is the integration's own long-lived job, on the data plane; an MCP tool call holds a hub connection only for its own length, so that part of the link is not a tool.
+
 ## Local Stdio
 
 The server speaks MCP over stdio and does not write logs to stdout.
@@ -325,6 +348,7 @@ Read-only:
 - `thalovant_list_hubs`
 - `thalovant_get_hub`
 - `thalovant_get_operation`
+- `thalovant_wait_for_admission`
 - `thalovant_identity_status`
 - `thalovant_healthcheck`
 - `thalovant_intent_inventory`
@@ -344,6 +368,12 @@ Skill and runtime-group discovery (read-only):
 - `thalovant_get_runtime_group_config`
 - `thalovant_get_hub_runtime_capabilities`
 
+Sign-in (see [Device Sign-In](#device-sign-in)):
+
+- `thalovant_begin_device_login`
+- `thalovant_poll_device_login`
+- `thalovant_revoke_device_login`
+
 Writes or hub events:
 
 - `thalovant_create_client_identity`
@@ -382,6 +412,7 @@ Destructive, **not registered unless explicitly enabled** (see [Destructive Tool
 
 - `thalovant_delete_hub`
 - `thalovant_delete_runtime_group`
+- `thalovant_delete_client`
 
 Tool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`. `savePath` is confined to the server's identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`): pass a plain filename, since absolute paths outside that directory and `..` traversal are rejected, so a model cannot drop a credential file into a git working tree or synced folder. `thalovant_config_status` reports the active `identityDir`.
 
@@ -403,6 +434,31 @@ unknown (empty lists/strings), with explanatory notes. Intent language order is
 explicit and survives JSON key sorting. Each tool call retains its own identity
 lease; the server does not persist inventory or share a session across callers.
 
+## Tool Errors
+
+When the Thalovant API refuses a control-plane call, the tool result is an
+error whose text starts with the SDK's one-line message (which names the HTTP
+status and can be shortened) and then says what the API said, in full:
+
+```text
+Thalovant API request failed with HTTP 403: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ... (platform_image_required)
+code: platform_image_required
+detail: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ghcr.io/thalovant/ovos-messagebus:2026.09.3-alpha.1, ghcr.io/thalovant/ovos-messagebus:2026.08.7; core may be any tag or digest of ghcr.io/thalovant/ovos-core.
+fields: {"allowed_images":{"bus":[...],"core":[...]},"allowed_repositories":{"core":"ghcr.io/thalovant/ovos-core"},"component":"runtime_group","refused_images":{...}}
+```
+
+- `code` is the API's machine-readable code, when it sent one.
+- `detail` is the whole sentence, and appears only when the first line had to
+  shorten it.
+- `fields` is every other member of the error body as compact JSON (the
+  Problem+JSON `type`, `title`, `status` and `instance` are left out), with the
+  same secret redaction as every other tool output. A value a validation error
+  echoes back from the request is redacted there and never reaches the first
+  line. A plan refusal carries `resource`, `limit`, `used` and `plan` here.
+
+A hint may follow for statuses that need one. A `platform_image_required` or
+`plan_limit` 403 gets its own hint rather than the general scope hint.
+
 ## Request hints, embedded audio, and configuration merging
 
 `thalovant_ask` accepts `sttLang`, an ordered `pipeline`, and `location`
@@ -432,9 +488,9 @@ or use an SDK that preserves large JSON integers.
 
 ## Destructive Tools
 
-`thalovant_delete_hub` and `thalovant_delete_runtime_group` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.
+`thalovant_delete_hub`, `thalovant_delete_runtime_group` and `thalovant_delete_client` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.
 
-A long-lived control-plane token combined with an always-available delete tool is a categorically different risk from a read or update tool: deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. So these two are opt-in:
+A long-lived control-plane token combined with an always-available delete tool is a categorically different risk from a read or update tool: deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. So these are opt-in:
 
 ```bash
 export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
@@ -452,7 +508,7 @@ export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group"
 
 The global deny applies to every principal and cannot be overridden by a principal's `allowedTools`. To restrict only selected principals, leave these tools out of the global denylist and use those principals' `deniedTools` instead.
 
-Deleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached.
+Deleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached. Deleting a client cuts off the device or link using it; its etag is read first when none is given.
 
 ## Non-Catalog Skill Sources
 
@@ -466,7 +522,7 @@ With the flag unset, a call with any `sourceType` other than `catalog` fails bef
 
 ## Read-Only Mode
 
-Set `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true`. Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.
+Set `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true` (the sign-in tools are not among them; `thalovant_wait_for_admission` is). Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.
 
 ## HiveMind Runtime Compatibility
 
@@ -474,7 +530,7 @@ Runtime calls sharing the same hub client identity run sequentially within one
 MCP process. Use a distinct client identity for each independently running MCP
 server so the hub can keep their sessions separate.
 
-Version 0.5.1 requires `@thalovant/sdk` `^0.7.1` (0.7.1 through versions below 0.8.0). This release enforces
+Version 0.6.0 requires `@thalovant/sdk` `^0.9.0` (0.9.0 through versions below 0.10.0). Since 0.5.1 the server enforces
 secure effective MQTT URLs and carries a single connection deadline through
 MQTT setup and HTTP failure cleanup. Runtime tools support
 HiveMind v3 Noise over WSS, HTTPS and MQTT over TLS. `thalovant_healthcheck`
@@ -552,7 +608,7 @@ one tool for every SDK conversation or event-listener method.
 
 ### Shared-runtime skill management
 
-The catalog has 46 default tools, 23 in read-only mode, and 48 with destructive tools enabled.
+The catalog has 50 default tools, 24 in read-only mode, and 53 with destructive tools enabled.
 
 Hub-addressed skill methods select the runtime group attached to the hub UUID.
 Every hub sharing that group sees the same skill changes and history. The API

package/dist/api-error-output.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a model reads when a control-plane call fails: the SDK's one-line
+ * message, then what the API actually said beside it.
+ *
+ * The message is bounded at 160 characters, and a structured refusal is
+ * usually longer than that -- a `platform_image_required` 403 names every
+ * image each refused key may be instead, and that list was the part cut off.
+ * So the code, the whole sentence (when the message line had to shorten it)
+ * and every other field of the body follow, as one compact JSON object.
+ * `redact` is the server's own secret redaction, applied to the fields: a
+ * validation error echoes back what it was sent.
+ *
+ * Returns undefined for anything that is not a `ThalovantApiError`.
+ */
+export declare function apiErrorText(error: unknown, redact: (value: unknown) => unknown): string | undefined;

package/dist/api-error-output.js

@@ -0,0 +1,54 @@
+import { ThalovantApiError } from "@thalovant/sdk";
+/**
+ * Problem+JSON members every refusal carries that say nothing the lines above
+ * them do not: the status is on the first line, and `type`/`title`/`instance`
+ * are the handler's own bookkeeping.
+ */
+const ENVELOPE = new Set(["type", "title", "status", "instance"]);
+/** A detail or a field list longer than this is cut, and says so. */
+const MAX_SECTION_CHARS = 4_000;
+function bounded(text) {
+    if (text.length <= MAX_SECTION_CHARS)
+        return text;
+    return `${text.slice(0, MAX_SECTION_CHARS)}… (${text.length - MAX_SECTION_CHARS} more characters)`;
+}
+/**
+ * What a model reads when a control-plane call fails: the SDK's one-line
+ * message, then what the API actually said beside it.
+ *
+ * The message is bounded at 160 characters, and a structured refusal is
+ * usually longer than that -- a `platform_image_required` 403 names every
+ * image each refused key may be instead, and that list was the part cut off.
+ * So the code, the whole sentence (when the message line had to shorten it)
+ * and every other field of the body follow, as one compact JSON object.
+ * `redact` is the server's own secret redaction, applied to the fields: a
+ * validation error echoes back what it was sent.
+ *
+ * Returns undefined for anything that is not a `ThalovantApiError`.
+ */
+export function apiErrorText(error, redact) {
+    if (!(error instanceof ThalovantApiError))
+        return undefined;
+    const lines = [error.message];
+    if (error.code)
+        lines.push(`code: ${error.code}`);
+    const shown = error.message.replace(/\s+/g, " ");
+    if (error.detail && !shown.includes(error.detail.replace(/\s+/g, " ").trim())) {
+        lines.push(`detail: ${bounded(error.detail)}`);
+    }
+    const problem = error.problem;
+    if (problem) {
+        const fields = {};
+        for (const [key, value] of Object.entries(problem)) {
+            if (ENVELOPE.has(key))
+                continue;
+            // Already on a line above when they were read as strings.
+            if ((key === "code" || key === "detail") && typeof value === "string")
+                continue;
+            fields[key] = value;
+        }
+        if (Object.keys(fields).length)
+            lines.push(`fields: ${bounded(JSON.stringify(redact(fields)))}`);
+    }
+    return lines.join("\n");
+}

package/dist/device-login.d.ts

@@ -0,0 +1,57 @@
+import type { DeviceAuthorization, ThalovantControlPlane } from "@thalovant/sdk";
+/**
+ * Device sign-ins, held by the server between the tool calls that run them.
+ *
+ * A tool call cannot wait for a person to approve a sign-in in a browser, so
+ * the device flow is two tools: one starts it and one polls it. What sits
+ * between them stays here, in this process, and never reaches the model: the
+ * device code (the secret half of the grant) behind an opaque login id, and
+ * the token an approved sign-in minted. Both belong to the principal that
+ * started the sign-in; another principal can neither poll it nor use its token.
+ */
+/** A sign-in started and not finished. */
+interface PendingLogin {
+    readonly principal: string;
+    readonly api: ThalovantControlPlane;
+    readonly authorization: DeviceAuthorization;
+    readonly expiresAt: number;
+}
+/** The token an approved sign-in minted, on the control plane that holds it. */
+export interface SignedIn {
+    readonly api: ThalovantControlPlane;
+    readonly origin: string;
+}
+export declare class DeviceLogins {
+    private readonly now;
+    private readonly pending;
+    private readonly signedIn;
+    /** The id of the token each principal last revoked, until it signs in again. */
+    private readonly revoked;
+    constructor(now?: () => number);
+    /**
+     * Keep a started sign-in for `principal`; returns the id its polls name it by.
+     *
+     * A principal holds at most a few at once, and starting another drops only
+     * its own oldest. Throws when the server as a whole holds as many as it will.
+     */
+    start(principal: string, api: ThalovantControlPlane, authorization: DeviceAuthorization): string;
+    /** The pending sign-in `loginId` names, if `principal` started it and it has not expired. */
+    find(loginId: string, principal: string): PendingLogin | undefined;
+    /** Forget a sign-in that ended: approved, expired or denied. */
+    finish(loginId: string): void;
+    /** Keep the token an approved sign-in minted, as `principal`'s. */
+    approve(principal: string, api: ThalovantControlPlane): void;
+    /** The token `principal` signed in with on `origin`, if there is one. */
+    signedInOn(principal: string, origin: string): SignedIn | undefined;
+    /** The token `principal` signed in with, wherever. */
+    signedInAs(principal: string): SignedIn | undefined;
+    /** Forget `principal`'s token, remembering its id as revoked. */
+    signOut(principal: string, tokenId?: string | null): void;
+    /**
+     * The id of the token `principal` signed out of, when it has signed out and
+     * not signed in since; undefined when it never signed out.
+     */
+    revokedOf(principal: string): string | null | undefined;
+    private prune;
+}
+export {};

package/dist/device-login.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+/** Sign-ins one principal may have pending at once; its own oldest is dropped first. */
+const MAX_PENDING_PER_PRINCIPAL = 4;
+/**
+ * Sign-ins pending at once across every principal. Past it a new sign-in is
+ * refused rather than evicting somebody else's: dropping another principal's
+ * sign-in would let one caller keep everyone else from ever signing in.
+ */
+const MAX_PENDING_LOGINS = 256;
+export class DeviceLogins {
+    now;
+    pending = new Map();
+    signedIn = new Map();
+    /** The id of the token each principal last revoked, until it signs in again. */
+    revoked = new Map();
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    /**
+     * Keep a started sign-in for `principal`; returns the id its polls name it by.
+     *
+     * A principal holds at most a few at once, and starting another drops only
+     * its own oldest. Throws when the server as a whole holds as many as it will.
+     */
+    start(principal, api, authorization) {
+        this.prune();
+        const own = [...this.pending].filter(([, login]) => login.principal === principal);
+        for (const [loginId] of own.slice(0, Math.max(0, own.length - MAX_PENDING_PER_PRINCIPAL + 1))) {
+            this.pending.delete(loginId);
+        }
+        if (this.pending.size >= MAX_PENDING_LOGINS) {
+            throw new Error("Too many device sign-ins are in progress on this server. Try again once some have finished or expired.");
+        }
+        const loginId = randomUUID();
+        this.pending.set(loginId, {
+            principal,
+            api,
+            authorization,
+            expiresAt: this.now() + authorization.expiresIn * 1000,
+        });
+        return loginId;
+    }
+    /** The pending sign-in `loginId` names, if `principal` started it and it has not expired. */
+    find(loginId, principal) {
+        this.prune();
+        const login = this.pending.get(loginId);
+        return login && login.principal === principal ? login : undefined;
+    }
+    /** Forget a sign-in that ended: approved, expired or denied. */
+    finish(loginId) {
+        this.pending.delete(loginId);
+    }
+    /** Keep the token an approved sign-in minted, as `principal`'s. */
+    approve(principal, api) {
+        this.signedIn.set(principal, { api, origin: new URL(api.apiUrl).origin });
+        this.revoked.delete(principal);
+    }
+    /** The token `principal` signed in with on `origin`, if there is one. */
+    signedInOn(principal, origin) {
+        const signedIn = this.signedIn.get(principal);
+        return signedIn && signedIn.origin === origin && signedIn.api.accessToken ? signedIn : undefined;
+    }
+    /** The token `principal` signed in with, wherever. */
+    signedInAs(principal) {
+        const signedIn = this.signedIn.get(principal);
+        return signedIn?.api.accessToken ? signedIn : undefined;
+    }
+    /** Forget `principal`'s token, remembering its id as revoked. */
+    signOut(principal, tokenId = null) {
+        this.signedIn.delete(principal);
+        this.revoked.set(principal, tokenId);
+    }
+    /**
+     * The id of the token `principal` signed out of, when it has signed out and
+     * not signed in since; undefined when it never signed out.
+     */
+    revokedOf(principal) {
+        return this.revoked.has(principal) ? this.revoked.get(principal) : undefined;
+    }
+    prune() {
+        const now = this.now();
+        for (const [loginId, login] of this.pending) {
+            if (login.expiresAt <= now)
+                this.pending.delete(loginId);
+        }
+    }
+}

package/dist/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { apiErrorText } from "./api-error-output.js";
+import { DeviceLogins } from "./device-login.js";
 import { inventoryPresentation } from "./inventory-output.js";
 import { runtimeReplyContent } from "./reply-output.js";
 import { throwIfRuntimeCancelled, withRuntimeLease } from "./runtime-lease.js";
@@ -6,7 +8,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { DEFAULT_CONTROL_API_URL, ThalovantClient, ThalovantControlPlane, ThalovantIdentity, buildClientContext, buildLocation, } from "@thalovant/sdk";
+import { CONNECTION_TYPE_HOME_ASSISTANT, DEFAULT_CONTROL_API_URL, HOME_ASSISTANT_SCOPES, ThalovantAdmissionFailedError, ThalovantAdmissionTimeoutError, ThalovantAlreadyLinkedError, ThalovantApiError, ThalovantApiUnreachableError, ThalovantAuthError, ThalovantClient, ThalovantControlPlane, ThalovantDeviceLoginDeniedError, ThalovantDeviceLoginExpiredError, ThalovantDeviceLoginPendingError, ThalovantIdentity, ThalovantPlanError, ThalovantUnsupportedConnectionTypeError, buildClientContext, buildLocation, } from "@thalovant/sdk";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
@@ -60,6 +62,10 @@ const SECRET_KEYS = [
     "secret",
 ];
 const protocolSchema = z.enum(["wss", "https", "mqtt"]);
+const connectionTypeSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{0,63}$/)
+    .describe(`The kind of connection, sent as spec.connection_type: voice_satellite, web_chat, developer, embedded, or ${CONNECTION_TYPE_HOME_ASSISTANT} for a Home Assistant link (one per hub). The kind decides what the connection may send and receive.`);
 const limitSchema = z.number().int().min(1).max(MAX_LIMIT).default(25).describe("Page size, 1-100.");
 const publicHubsLimitSchema = z
     .number()
@@ -123,7 +129,14 @@ const runtimeAuthSchema = {
  * they are absent from tools/list entirely rather than merely failing when
  * called. See destructiveToolsEnabled().
  */
-const DESTRUCTIVE_TOOLS = ["thalovant_delete_hub", "thalovant_delete_runtime_group"];
+const DESTRUCTIVE_TOOLS = ["thalovant_delete_hub", "thalovant_delete_runtime_group", "thalovant_delete_client"];
+/**
+ * Device sign-ins in progress, and the tokens approved ones minted, per
+ * principal, for the life of this process. See device-login.ts.
+ */
+const deviceLogins = new DeviceLogins();
+/** How long thalovant_wait_for_admission waits by default: a hub admits a new connection in about ninety seconds. */
+const ADMISSION_DEFAULT_TIMEOUT_MS = 120_000;
 /**
  * Destructive control-plane tools are opt-in.
  *
@@ -204,22 +217,30 @@ const releaseOptionsSchema = {
     channel: z.string().min(1).optional().describe("Release channel. Falls back to the workspace release policy when omitted."),
     mode: z.string().min(1).optional().describe('Release mode. Passing images without mode switches to "custom".'),
     version: z.string().min(1).optional().describe("Pinned release version."),
-    images: z.record(z.string().min(1)).optional().describe("Explicit image overrides. Switches to custom mode unless mode is also set."),
+    images: z.record(z.string().min(1)).optional().describe("Explicit image overrides. Switches to custom mode unless mode is also set. Non-admins may pass only images the platform releases for each key: a catalog pin of the stable or alpha channel, the resource's current, recommended or release-policy image, or the platform's default image; runtime core also accepts any tag or digest of ghcr.io/thalovant/ovos-core and hub listener any tag or digest of ghcr.io/thalovant/hivemind-listener, while bus and preview_bridge take only the listed images. Anything else fails with 403 platform_image_required, whose error lists allowed_images and allowed_repositories per refused key."),
     reason: z.string().min(1).optional().describe("Audit reason recorded with the release."),
 };
 function releaseOptionsFrom(args) {
     return { channel: args.channel, mode: args.mode, version: args.version, images: args.images, reason: args.reason };
 }
 const SCOPE_HINT_403 = 'HTTP 403 "Insufficient scopes" — the token lacks the scope this route needs: hubs:write for provisioning, hubs:read for the marketplace catalog, hubs:inspect for runtime-group and hub runtime views (hubs:write implies hubs:read, which implies hubs:inspect and hubs:preview). The API checks scope BEFORE the paid-plan gate, so a 403 can mask a plan problem and granting the scope may surface a 402 next. Free-plan API tokens are capped at hubs:read, clients:read, and clients:write, so a free-tier API token fails provisioning with this 403 and never reaches the 402. A 403 here can also mean the caller does not own the resource ("Ownership required"), or a plan restriction such as HUB_AUTOSCALING_NOT_INCLUDED or a custom hub domain the plan does not allow.';
+const PLATFORM_IMAGE_HINT_403 = 'HTTP 403 platform_image_required — only a platform administrator can run an image the platform does not release. This is not a scope problem: pick, for each key in refused_images, one of that key\'s allowed_images, or any tag or digest of its allowed_repositories entry (both are in the fields above), and retry.';
+const PLAN_LIMIT_HINT_403 = 'HTTP 403 plan_limit — the plan\'s allowance for the named resource is used up (see resource, used and limit in the fields above). Granting a scope will not help: free one (delete or reuse an existing one) or move the workspace to a larger plan.';
 const PLAN_HINT_402 = 'HTTP 402 "API access requires a paid plan." — the token is valid and correctly scoped but the tenant is on the free plan. Free-tier callers can browse the catalog (thalovant_list_marketplace_skills) and set hub ratings, but cannot create, update, release, or delete hubs and runtime groups, and cannot install skills.';
 const MARKETPLACE_HINT_402 = 'HTTP 402 "This skill requires paid marketplace access for the tenant plan." — a DIFFERENT 402 from the plan gate: the plan is paid enough to provision, but this catalog entry has access_tier "paid" and the plan does not include paid marketplace skills. thalovant_list_runtime_group_marketplace reports this per skill as purchase_required, installable, and access_message; check it before installing.';
 const HUB_SKILL_HINT_422 = 'HTTP 422 — the requested hub skill version is unusable: "latest" could not be resolved to a published version of that skill, or the version string is not a valid version. Check the skill name and its published versions with thalovant_list_marketplace_skills, or pass an explicit x.y.z.';
 const ETAG_HINT_412 = 'HTTP 412 "ETag mismatch" — the If-Match etag was missing or stale and nothing changed. Re-fetch the hub with thalovant_get_hub, read the `etag` field from the response BODY (there is no ETag response header), and retry with that exact value. The comparison is exact string equality, so do not rewrite or weaken the value.';
-function controlPlaneErrorHint(profile, status, body) {
+function controlPlaneErrorHint(profile, status, body, code) {
     switch (status) {
         case 402:
             return (profile === "skillInstall" || profile === "hubSkillInstall") && /marketplace/i.test(body) ? MARKETPLACE_HINT_402 : PLAN_HINT_402;
         case 403:
+            // A 403 that names its reason is not the scope problem the general hint
+            // describes, and sending a model off to grant scopes wastes the turn.
+            if (code === "platform_image_required")
+                return PLATFORM_IMAGE_HINT_403;
+            if (code === "plan_limit")
+                return PLAN_LIMIT_HINT_403;
             return SCOPE_HINT_403;
         case 404:
             return /hub_without_runtime_group/.test(body)
@@ -238,12 +259,47 @@ function controlPlaneErrorHint(profile, status, body) {
             return undefined;
     }
 }
+/**
+ * Guidance for a refused connection create or delete, by the SDK's class for
+ * the refusal. Undefined when the class says nothing a hint could add to.
+ */
+function connectionErrorHint(error, connectionType) {
+    if (error instanceof ThalovantUnsupportedConnectionTypeError) {
+        return error.statusCode === undefined
+            ? `The API made an ordinary connection instead of a ${JSON.stringify(connectionType)} one, so the server deleted it again (the message says if that failed). This API does not support the kind yet; retrying will not change that.`
+            : `The API does not know the connection type ${JSON.stringify(connectionType)} yet (HTTP 422). Retrying will not change that; omit connectionType for an ordinary connection.`;
+    }
+    if (error instanceof ThalovantAlreadyLinkedError) {
+        return `A hub takes one Home Assistant connection, and this one already has it${error.clientId ? `: client ${error.clientId}` : ""}. Use that connection, or delete it with thalovant_delete_client (a destructive tool the operator enables) and create the link again.`;
+    }
+    if (error instanceof ThalovantPlanError) {
+        return error.code === "plan_limit"
+            ? "The plan's connections are used up (see resource, used and limit in the fields above). Delete one with thalovant_delete_client, or move the workspace to a larger plan; granting a scope will not help."
+            : "The plan does not allow this connection (HTTP 402). Move the workspace to a paid plan; granting a scope will not help.";
+    }
+    if (error instanceof ThalovantAuthError) {
+        return "The API refused the token itself: it is unknown, expired or revoked (401), the account is locked (423), or it lacks clients:write (403 Insufficient scopes). Sign in again with thalovant_begin_device_login, or configure a token that carries clients:read and clients:write.";
+    }
+    if (error instanceof ThalovantApiUnreachableError) {
+        return "The Thalovant API could not be reached, which says nothing about the connection: it may be admitted, or created, all the same. Try again once the API answers; do not create another connection before checking.";
+    }
+    return undefined;
+}
+/** Rethrow a refused connection call with its guidance, when it has any. */
+function withConnectionHint(error, connectionType) {
+    const hint = connectionErrorHint(error, connectionType);
+    if (!hint)
+        throw error;
+    const said = apiErrorText(error, redactSecrets) ?? (error instanceof Error ? error.message : String(error));
+    throw new Error(`${said}\n\n${hint}`, { cause: error });
+}
 /**
  * Run a control-plane call and, on failure, append actionable guidance.
  *
- * The SDK raises ThalovantApiError with the status embedded in the message
- * ("Thalovant API request failed with HTTP 412: ..."), so the status is
- * recovered by parsing rather than from a structured field.
+ * The status and code come from the SDK's ThalovantApiError. What the API
+ * said -- the code, the whole sentence, every other field of the body -- goes
+ * ahead of the hint (see apiErrorText); an error that is not an API error
+ * keeps its own message, and its status is read from it when it names one.
  */
 async function callControlPlane(profile, run) {
     try {
@@ -251,11 +307,13 @@ async function callControlPlane(profile, run) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const status = Number(/HTTP (\d{3})/.exec(message)?.[1]);
-        const hint = Number.isFinite(status) ? controlPlaneErrorHint(profile, status, message) : undefined;
+        const apiError = error instanceof ThalovantApiError ? error : undefined;
+        const status = apiError?.statusCode ?? Number(/HTTP (\d{3})/.exec(message)?.[1]);
+        const said = [message, apiError?.code, apiError?.detail].filter(Boolean).join(" ");
+        const hint = Number.isFinite(status) ? controlPlaneErrorHint(profile, status, said, apiError?.code) : undefined;
         if (!hint)
             throw error;
-        throw new Error(`${message}\n\n${hint}`);
+        throw new Error(`${apiErrorText(error, redactSecrets) ?? message}\n\n${hint}`, { cause: error });
     }
 }
 const HUB_SKILL_DEFAULT_TIMEOUT_MS = 120_000;
@@ -586,7 +644,12 @@ function registerThalovantTool(server, name, config, handler) {
                 durationMs: Date.now() - start,
                 error: error instanceof Error ? error.message : String(error),
             });
-            throw error;
+            // An API error that no hint was added to still says what the API said:
+            // the SDK's message is one bounded line, and the structured fields a
+            // refusal carries (the images a caller may pin, a plan's numbers) are
+            // only on the error itself.
+            const text = apiErrorText(error, redactSecrets);
+            throw text === undefined ? error : new Error(text, { cause: error });
         }
     });
 }
@@ -610,17 +673,38 @@ function redactSecrets(value) {
     }
     return output;
 }
+/** The control-plane URL this principal's credentials belong to. */
+async function configuredControlApiUrl(principal = currentPrincipal()) {
+    const credential = await credentialForPrincipal(principal);
+    const canUseShared = allowSharedThalovantCredentials(principal);
+    return credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+}
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Keep server-managed credentials on their configured control-plane origin. */
 async function createControlPlane(options) {
     const principal = currentPrincipal();
     const credential = await credentialForPrincipal(principal);
     const canUseShared = allowSharedThalovantCredentials(principal);
-    const configuredApiUrl = credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+    const configuredApiUrl = await configuredControlApiUrl(principal);
     const apiUrl = options.apiUrl ?? configuredApiUrl;
-    const accessToken = credential?.control?.accessToken ??
-        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
     const email = canUseShared ? process.env.THALOVANT_EMAIL : undefined;
     const password = canUseShared ? process.env.THALOVANT_PASSWORD : undefined;
+    const configuredToken = credential?.control?.accessToken ??
+        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
+    // With nothing configured, the token this principal signed in with through
+    // thalovant_begin_device_login / thalovant_poll_device_login, which exists
+    // only for the configured origin.
+    const signedIn = configuredToken || (email && password)
+        ? undefined
+        : deviceLogins.signedInOn(principal.id, originOf(configuredApiUrl) ?? "");
+    const accessToken = configuredToken ?? signedIn?.api.accessToken;
     if (accessToken || (email && password)) {
         let endpoint;
         let configuredEndpoint;
@@ -655,6 +739,24 @@ function ensureAuthenticated(api) {
         throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_API_TOKEN (recommended: a scoped, revocable API token), THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
     }
 }
+/**
+ * A control plane for a device sign-in, on the configured API origin only.
+ *
+ * It carries no credential: the sign-in is what mints one. The origin is fixed
+ * because the verification URL the API answers with is shown to a person, and
+ * the token it mints is kept here for later calls; a tool argument must not
+ * send either somewhere else.
+ */
+async function deviceLoginControlPlane(apiUrl) {
+    const configuredApiUrl = await configuredControlApiUrl();
+    const configured = originOf(configuredApiUrl);
+    if (!configured)
+        throw new Error("The configured control-plane API URL is invalid.");
+    if (apiUrl !== undefined && originOf(apiUrl) !== configured) {
+        throw new Error("apiUrl must use the configured Thalovant API origin for a device sign-in.");
+    }
+    return new ThalovantControlPlane(apiUrl ?? configuredApiUrl, { userAgent: `thalovant-mcp/${VERSION}` });
+}
 function controlPlaneAuthModeFromEnv() {
     if (process.env.THALOVANT_API_TOKEN)
         return "api-token";
@@ -1155,6 +1257,7 @@ export function createServer() {
     }, async () => jsonContent({
         apiUrl: process.env.THALOVANT_API_URL ?? DEFAULT_CONTROL_API_URL,
         controlPlaneAuthMode: controlPlaneAuthModeFromEnv(),
+        deviceLoginSignedIn: Boolean(deviceLogins.signedInAs(currentPrincipal().id)),
         hasApiToken: Boolean(process.env.THALOVANT_API_TOKEN),
         hasAccessToken: Boolean(process.env.THALOVANT_ACCESS_TOKEN),
         hasEmailPassword: Boolean(process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD),
@@ -1248,7 +1351,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_create_client_identity", {
         title: "Create Client Identity",
-        description: "Create a Thalovant client identity for a hub. The identity is secret; output is redacted unless savePath is used.",
+        description: "Create a Thalovant client identity (a hub connection) for a hub. The identity is secret; output is redacted unless savePath is used. Pass connectionType (for example home_assistant) for a connection of that kind: the API must answer with the same kind, or the connection it made instead is deleted and the call fails. A new connection is admitted by its hub in about ninety seconds; follow operationId with thalovant_wait_for_admission before connecting.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z
@@ -1262,6 +1365,7 @@ export function createServer() {
             preferredProtocols: z.array(protocolSchema).min(1).default(["wss", "https"]),
             idempotencyKey: z.string().min(1).optional(),
             spec: jsonRecordSchema.optional(),
+            connectionType: connectionTypeSchema.optional(),
             savePath: z
                 .string()
                 .min(1)
@@ -1274,7 +1378,7 @@ export function createServer() {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, savePath, ...auth }) => {
+    }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, connectionType, savePath, ...auth }) => {
         // Validate the destination BEFORE creating a cloud identity, so a path
         // that escapes the identity directory is refused without leaving an
         // orphaned credential behind in the control plane.
@@ -1289,19 +1393,180 @@ export function createServer() {
             preferredProtocols,
             idempotencyKey,
             spec,
-        });
+            connectionType,
+        }).catch((error) => withConnectionHint(error, connectionType));
         const selectedEndpoint = api.requireRuntimeProtocol(result, preferredProtocols[0]);
         const savedIdentityPath = targetIdentityPath ? await writeIdentityFile(targetIdentityPath, result.identity) : undefined;
         return jsonContent({
             result: redactSecrets(result.asObject({ includeSecrets: false })),
+            clientId: result.clientId ?? null,
+            connectionType: result.connectionType ?? null,
+            operationId: result.operation?.id ?? null,
             selectedEndpoint,
             enabledProtocols: result.identity.enabledProtocols(),
             savedIdentityPath,
             secretNotice: savedIdentityPath
                 ? "Full identity was written to the requested local path with mode 0600."
                 : "Secret identity fields were not returned. Pass savePath to write a protected local identity file.",
+            next: result.operation
+                ? "The hub admits a new connection in about ninety seconds and refuses it until then. Call thalovant_wait_for_admission with this operationId before connecting."
+                : "The API returned no admission operation, so there is nothing to wait for.",
         });
     });
+    registerThalovantTool(server, "thalovant_wait_for_admission", {
+        title: "Wait For Connection Admission",
+        description: "Wait until a hub admits a connection made with thalovant_create_client_identity: about ninety seconds after the create. Follows the operation the create returned (operationId), reading it every pollIntervalMs; a 429 is waited out for the time the API names. outcome is admitted (ready, or an operation the API no longer tracks), failed -- the platform could not admit it (errorCode says why, status is null) or the API refused the wait itself (status, code and detail say what it answered) -- or timeout: timeoutMs passed first and the connection may still be admitted, so call this tool again rather than creating another connection. A token the API refuses (401, 403) or an API out of reach is a tool error of its own, not a failed admission. Omit operationId when the create returned none. Reads only.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            operationId: z
+                .string()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("operationId from thalovant_create_client_identity: the operation's id or its links.self path. An absolute URL must be on the API's own origin."),
+            timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(ADMISSION_DEFAULT_TIMEOUT_MS),
+            pollIntervalMs: z.number().int().min(500).max(10_000).default(2_000).describe("Milliseconds between two reads of the operation."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ operationId, timeoutMs, pollIntervalMs, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const signal = requestContext.getStore()?.signal;
+        throwIfRuntimeCancelled(signal);
+        try {
+            await api.waitForAdmission(operationId ?? null, { timeoutMs: clampTimeout(timeoutMs), pollIntervalMs, signal });
+            return jsonContent({ outcome: "admitted" });
+        }
+        catch (error) {
+            if (error instanceof ThalovantAdmissionTimeoutError) {
+                return jsonContent({
+                    outcome: "timeout",
+                    next: "The hub has not admitted the connection yet and may still. Call thalovant_wait_for_admission again with the same operationId; do not create another connection.",
+                });
+            }
+            if (error instanceof ThalovantAdmissionFailedError) {
+                // The API's own words when it refused the wait; null for a failure on the platform.
+                return jsonContent(redactSecrets({
+                    outcome: "failed",
+                    errorCode: error.errorCode ?? null,
+                    status: error.statusCode ?? null,
+                    code: error.code ?? null,
+                    detail: error.detail ?? null,
+                    message: error.message,
+                }));
+            }
+            throwIfRuntimeCancelled(signal);
+            withConnectionHint(error);
+        }
+    });
+    registerThalovantTool(server, "thalovant_begin_device_login", {
+        title: "Begin Device Sign-In",
+        description: "Start a device sign-in (RFC 8628) when no API token is configured: a person approves it in a browser. Show the person verificationUri and userCode (or verificationUriComplete, which carries the code), then call thalovant_poll_device_login with loginId every `interval` seconds. The device code stays on this server. Once approved, control-plane tools for this principal use the token it minted. A Home Assistant link asks for hubs:read, clients:read and clients:write, which is also all a Free plan can approve.",
+        inputSchema: {
+            apiUrl: controlPlaneSchema.apiUrl,
+            scopes: z
+                .array(z.string().min(1).max(64))
+                .max(32)
+                .optional()
+                .describe(`Scopes the token will carry. The API applies its default when omitted or empty (an empty list is left out of the request). A Home Assistant link asks for ${HOME_ASSISTANT_SCOPES.join(", ")}.`),
+            clientName: z.string().min(1).max(128).optional().describe("The name the approval page and the dashboard's token list show."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ apiUrl, scopes, clientName }) => {
+        const api = await deviceLoginControlPlane(apiUrl);
+        const grant = await api.beginDeviceLogin({ scopes, clientName });
+        const loginId = deviceLogins.start(currentPrincipal().id, api, grant);
+        return jsonContent({
+            loginId,
+            userCode: grant.userCode,
+            verificationUri: grant.verificationUri,
+            verificationUriComplete: grant.verificationUriComplete,
+            interval: grant.interval,
+            expiresIn: grant.expiresIn,
+            next: `Ask the person to open ${grant.verificationUri} and enter ${grant.userCode}, then call thalovant_poll_device_login with this loginId every ${grant.interval} seconds until the outcome is no longer pending. The code expires in ${grant.expiresIn} seconds.`,
+        });
+    });
+    registerThalovantTool(server, "thalovant_poll_device_login", {
+        title: "Poll Device Sign-In",
+        description: "Ask once whether the person approved a device sign-in started with thalovant_begin_device_login. outcome is pending (poll again after `interval` seconds, already lengthened if the API asked to slow down), approved (control-plane tools for this principal now use the token; tokenId, scopes and expiresAt describe it), expired or denied (begin a new sign-in). The token itself is never returned.",
+        inputSchema: {
+            loginId: z.string().min(1).max(64).describe("loginId from thalovant_begin_device_login."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ loginId }) => {
+        const principal = currentPrincipal().id;
+        const login = deviceLogins.find(loginId, principal);
+        if (!login) {
+            throw new Error("No device sign-in in progress has this loginId: it expired, already ended, or was started by another principal. Begin a new one with thalovant_begin_device_login.");
+        }
+        try {
+            const token = await login.api.pollDeviceLogin(login.authorization);
+            deviceLogins.finish(loginId);
+            deviceLogins.approve(principal, login.api);
+            return jsonContent({
+                outcome: "approved",
+                tokenType: token.tokenType,
+                scopes: [...token.scopes],
+                expiresAt: token.expiresAt,
+                tokenId: token.tokenId,
+                next: "Signed in. Control-plane tools for this principal now use this token until thalovant_revoke_device_login or a server restart.",
+            });
+        }
+        catch (error) {
+            if (error instanceof ThalovantDeviceLoginPendingError) {
+                return jsonContent({ outcome: "pending", interval: error.interval });
+            }
+            if (error instanceof ThalovantDeviceLoginExpiredError) {
+                deviceLogins.finish(loginId);
+                return jsonContent({ outcome: "expired", status: error.statusCode ?? null, next: "The code expired before anybody approved it. Begin a new sign-in." });
+            }
+            if (error instanceof ThalovantDeviceLoginDeniedError) {
+                deviceLogins.finish(loginId);
+                return jsonContent({ outcome: "denied", status: error.statusCode ?? null, next: "The person declined the sign-in in the browser." });
+            }
+            throw error;
+        }
+    });
+    registerThalovantTool(server, "thalovant_revoke_device_login", {
+        title: "Revoke Device Sign-In",
+        description: "Sign out: revoke the API token this principal signed in with through thalovant_poll_device_login, and stop using it. A token may always revoke itself, and one already revoked counts as revoked; signing out again answers alreadyRevoked without a request. Tokens configured on the server are never touched.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        const principal = currentPrincipal().id;
+        const signedIn = deviceLogins.signedInAs(principal);
+        if (!signedIn) {
+            // Signing out twice is signing out once: the token is already gone.
+            const earlier = deviceLogins.revokedOf(principal);
+            if (earlier !== undefined)
+                return jsonContent({ revoked: true, tokenId: earlier, alreadyRevoked: true });
+            throw new Error("This principal has not signed in with a device sign-in, so there is no token of its own to revoke.");
+        }
+        const tokenId = signedIn.api.tokenId ?? null;
+        // A token the API no longer accepts (401 on its own revoke) is already
+        // revoked; the SDK counts that as done.
+        await signedIn.api.revokeApiToken();
+        deviceLogins.signOut(principal, tokenId);
+        return jsonContent({ revoked: true, tokenId });
+    });
     registerThalovantTool(server, "thalovant_identity_status", {
         title: "Identity Status",
         description: "Load a Thalovant identity and return redacted protocol and endpoint status.",
@@ -1879,7 +2144,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_release_hub", {
         title: "Release Hub",
-        description: "Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan. No etag is needed.",
+        description: "Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set; non-admins may pass only images the platform releases (see images). Requires the hubs:write scope and a paid plan. No etag is needed.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID."),
@@ -2072,7 +2337,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_release_runtime_group", {
         title: "Release Runtime Group",
-        description: "Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan.",
+        description: "Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set (non-admins: only images the platform releases, see images). Requires the hubs:write scope and a paid plan.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
@@ -2277,6 +2542,26 @@ export function createServer() {
             await callControlPlane("hubWrite", () => api.deleteHub(hubId, { etag }));
             return textContent("Hub deleted.");
         });
+        registerThalovantTool(server, "thalovant_delete_client", {
+            title: "Delete Client",
+            description: "Permanently delete a client (a hub connection): the device or link using it loses access to the hub. This cannot be undone. etag is the client's current etag, sent as If-Match; when omitted the server reads it first. A client changed underneath (412) is read again and the delete retried once, and a client already gone counts as deleted. Requires the clients:write scope. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.",
+            inputSchema: {
+                ...controlPlaneSchema,
+                clientId: z.string().min(1).max(128).describe("Client UUID, for example the clientId a create returned or the client_id of an already-linked refusal."),
+                etag: z.string().min(1).optional().describe("The client's current etag. Read first when omitted."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async ({ clientId, etag, ...auth }) => {
+            const api = await createControlPlane(auth);
+            ensureAuthenticated(api);
+            await api.deleteClient(clientId, { etag }).catch((error) => withConnectionHint(error));
+            return jsonContent({ deleted: true, clientId });
+        });
         registerThalovantTool(server, "thalovant_delete_runtime_group", {
             title: "Delete Runtime Group",
             description: "Permanently delete a Thalovant runtime group. This cannot be undone. The API answers HTTP 409 for the workspace default group and for a group that still has hubs attached — move or delete those hubs first. This route takes no etag. Requires the hubs:write scope and a paid plan. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@thalovant/sdk": "^0.8.2",
+    "@thalovant/sdk": "^0.9.0",
     "jose": "^6.2.8",
     "zod": "^3.25.76"
   },

package/server.json

@@ -7,19 +7,19 @@
     "url": "https://github.com/thalovant/thalovant-mcp",
     "source": "github"
   },
-  "version": "0.5.2",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.5.2",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.6.0",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"