@thalovant/mcp-server 0.1.24 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 — 2026-09-12
+
+- Use Node SDK 0.5.0 request hints, bounded embedded audio replies, and speakable intent examples. Keep embedded audio out of model text; offer explicit audio/resource content blocks through includeAudio.
+- Default runtime configuration tools to revision-guarded merging with at most three attempts and only HTTP 412 retries. Preserve explicit replacement with merge: false. Guarded merging requires hubs:read and paid hubs:write.
+- Cover actual encrypted runtime hints/audio and default conditional-write conflict handling through MCP tool calls. Preserve the existing tool catalog and align npm/OCI/registry versions.
+
+## 0.2.0 — 2026-09-12
+
+- Add a read-only hub skill history tool using Node SDK 0.4.0. The catalog now has 46 default tools, 23 in read-only mode, and 48 with destructive tools enabled.
+- Correct shared-runtime skill scope and token requirements.
+
 ## 0.1.24
 
 - Require Node SDK 0.3.16 and use its public hub-skill methods instead of the temporary duplicate HTTP and polling implementation. Preserve tool schemas, accepted-operation output, API guidance and MCP cancellation checks.

package/README.md

@@ -56,8 +56,8 @@ Minimum scopes for the full control-plane tool surface:
 
 | Scope | Used by |
 |-------|---------|
-| `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`, 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` |
+| `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`) |
 | `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |
@@ -81,7 +81,7 @@ Grant fewer scopes for narrower deployments: a read-only assistant needs only `h
 
 ### Hub Skills
 
-`thalovant_list_hub_skills`, `thalovant_install_hub_skill`, `thalovant_update_hub_skill`, and `thalovant_remove_hub_skill` act on **one hub**, not on a runtime group's skill set. A hub can start with no skills at all and gain them one at a time; a change applies live on the hub in about 15 seconds with no restart. `hubId` must be the hub UUID — the authenticated hub routes reject slugs.
+`thalovant_list_hub_skills`, `thalovant_install_hub_skill`, `thalovant_update_hub_skill`, and `thalovant_remove_hub_skill` select a hub's attached runtime group; all hubs sharing it are affected. A hub can start with no skills at all and gain them one at a time; a change applies live on the hub in about 15 seconds with no restart. `hubId` must be the hub UUID — the authenticated hub routes reject slugs.
 
 `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`.
 
@@ -368,9 +368,10 @@ Hub and runtime-group provisioning:
 - `thalovant_install_runtime_group_skill`
 - `thalovant_uninstall_runtime_group_skill`
 
-Hub skills, acting on one hub (see [Hub Skills](#hub-skills); the list tool is read-only):
+Hub skills, acting on the hub’s shared runtime (see [Hub Skills](#hub-skills); the list tool is read-only):
 
 - `thalovant_list_hub_skills`
+- `thalovant_list_hub_skill_history`
 - `thalovant_install_hub_skill`
 - `thalovant_update_hub_skill`
 - `thalovant_remove_hub_skill`
@@ -383,7 +384,7 @@ Destructive, **not registered unless explicitly enabled** (see [Destructive Tool
 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`.
 
 `thalovant_intent_inventory` uses the runtime identity and accepts `languages`,
-`describe`, `fallback`, and a per-query/batch `timeoutMs`. It returns registered
+`describe`, `fallback`, `speakable`, `slots`, `exampleLimit`, and a per-query/batch `timeoutMs`. It returns registered
 intents and examples, fallback skills, `fallbacks_known`, and `may_answer` by
 requested language. A missing or denied optional fallback-skill query remains
 unknown, rather than being reported as a known empty list. The optional probe
@@ -392,6 +393,33 @@ adds at most 1500ms. A silent listing can use engine manifests; disable this wit
 per-principal policy. `thalovant_get_operation` reads an operation ID returned by
 provisioning without replaying the write.
 
+## Request hints, embedded audio, and configuration merging
+
+`thalovant_ask` accepts `sttLang`, an ordered `pipeline`, and `location`
+with required `city` and optional `region`, `country`, `timezone`, `latitude`,
+and `longitude`. Hints apply to the current request. Omit unused hints;
+an empty pipeline is ignored, and blank language or city strings are rejected.
+
+Ask and Query return language, ordered event metadata, `hasAudio` and
+`droppedMedia`. Embedded hex stays out of text output. Opt into separate MCP
+audio blocks with `includeAudio: true`; unknown formats become embedded binary
+resource blocks. Clip and reply limits are 4 MiB and 16 MiB respectively,
+checked by the SDK before retention. The client owns playback. No skill-supplied
+path or URL is fetched. Inventory `speakable: true` renders examples without
+changing the raw patterns; `slots` supplies illustrative slot values, and
+`exampleLimit` limits examples per language to 1–20 (default 2).
+
+Configuration updates default to `merge: true`: GET the revision, deep-merge
+the caller's delta and PUT with `expected_revision`. Only HTTP 412 retries,
+with a fresh read and at most three total attempts. This requires `hubs:read`,
+`hubs:write`, and a paid plan. An older API without revision support fails before
+writing. There is no unconditional fallback. Supplied personas replace;
+omitted personas stay unchanged. For an intentional full replacement, pass
+`merge: false`, requiring `hubs:write`, a paid plan, and coordination with other writers.
+Guarded merges reject integers outside JavaScript's safe integer range in the
+delta or stored configuration before writing. Store large identifiers as strings
+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.
@@ -436,7 +464,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.1.24 uses `@thalovant/sdk` `^0.3.16` (0.3.16 through versions below 0.4.0). This release enforces
+Version 0.3.0 requires `@thalovant/sdk` `^0.5.1` (0.5.1 through versions below 0.6.0). This release 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`
@@ -510,3 +538,22 @@ options, and returns the same normalized reply shape as `thalovant_ask`. A query
 may trigger actions, so read-only mode hides it. Conversation workflows use
 `sessionId` with ask/query and the existing event-wait tool; MCP does not expose
 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.
+
+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
+requires a restricted token to cover all served hubs. Reads need `hubs:inspect`
+(`hubs:read` implies it); writes need `hubs:write`, an eligible paid plan and ownership.
+
+The history response contains newest-first `event` and `operation` entries,
+including nullable actor/version fields. Its limit is 1–200 (50 where omitted).
+An accepted mutation is not proof the skill is ready. Optional waiting polls the
+operation, with a 120-second default timeout and two-second interval. Polling
+never repeats an accepted mutation and starts no new read after its deadline;
+an already-running HTTP request retains its normal request timeout.
+
+Read history with `thalovant_list_hub_skill_history` (`hubId`, optional `limit`). This tool remains available in read-only mode.

package/dist/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { runtimeReplyContent } from "./reply-output.js";
 import { throwIfRuntimeCancelled, withRuntimeLease } from "./runtime-lease.js";
 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, } from "@thalovant/sdk";
+import { DEFAULT_CONTROL_API_URL, ThalovantClient, ThalovantControlPlane, ThalovantIdentity, 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";
@@ -718,21 +719,6 @@ async function withRuntimeClient(options, run) {
     ])).digest("hex");
     return withRuntimeLease(key, () => new ThalovantClient(identity, { protocol: options.protocol ?? "wss" }), client => run(client, signal), 6000, signal);
 }
-function summarizeReply(reply) {
-    const displayItems = reply.displayItems({ maxTextChars: 1_000 });
-    return {
-        text: reply.text,
-        displayText: reply.displayText,
-        utterances: reply.utterances,
-        handled: reply.handled,
-        ok: reply.ok,
-        sessionId: reply.sessionId,
-        requestId: reply.requestId,
-        displayItems,
-        events: reply.events.map((event) => redactSecrets(event.asObject())),
-        failureEvent: reply.failureEvent ? redactSecrets(reply.failureEvent.asObject()) : undefined,
-    };
-}
 /**
  * Base directory that saved client-identity files are confined to.
  *
@@ -1360,17 +1346,23 @@ export function createServer() {
         inputSchema: {
             ...runtimeAuthSchema,
             languages: z.array(z.string().trim().min(1).max(100)).min(1).max(20).default(["en-us"]),
+            speakable: z.boolean().default(false).describe("Render intent patterns into example sentences; preserve whole-sentence priority."),
+            slots: z.record(z.string().max(500)).optional().describe("Example values for named intent slots."),
+            exampleLimit: z.number().int().min(1).max(20).default(2),
             describe: z.boolean().default(true),
             fallback: z.boolean().default(true).describe("Try engine manifests if the intent listing is refused or unanswered."),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS).describe("Per-query/batch timeout; the optional fallback-skill probe is capped at 1500ms."),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ languages, describe, fallback, timeoutMs, ...runtime }) => withRuntimeClient(runtime, async (client, signal) => {
+    }, async ({ languages, describe, fallback, timeoutMs, speakable, slots, exampleLimit, ...runtime }) => withRuntimeClient(runtime, async (client, signal) => {
         await client.connect(undefined, signal);
         throwIfRuntimeCancelled(signal);
         const inventory = await client.intents(languages, { describe, fallback, timeoutMs: clampTimeout(timeoutMs) });
         return jsonContent(redactSecrets({
             ...inventory.asObject(),
+            examples: inventory.intents.map(intent => ({ id: intent.id,
+                languages: Object.fromEntries(inventory.languages.map(lang => [lang, intent.examples(lang, exampleLimit, { speakable, slots })])),
+            })),
             may_answer: Object.fromEntries(inventory.languages.map(lang => [lang, inventory.mayAnswer(lang)])),
         }));
     }));
@@ -1381,6 +1373,12 @@ export function createServer() {
             ...runtimeAuthSchema,
             text: z.string().min(1).max(20_000),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
+            sttLang: z.string().trim().min(1).max(100).optional().describe("Language recognized by speech-to-text; the hub validates this hint."),
+            pipeline: z.array(z.string().trim().min(1).max(200)).max(32).optional(),
+            location: z.object({ city: z.string().trim().min(1).max(500), region: z.string().max(500).optional(), country: z.string().max(100).optional(),
+                latitude: z.number().finite().min(-90).max(90).optional(), longitude: z.number().finite().min(-180).max(180).optional(), timezone: z.string().max(200).optional(),
+            }).optional().describe("Request location, preferred over the hub's configured city."),
+            includeAudio: z.boolean().default(false).describe("Include bounded embedded skill clips as MCP audio/resources; default returns metadata without placing audio hex in text."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1394,7 +1392,7 @@ export function createServer() {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ text, timeoutMs, lang, sessionId, requestId, context, replySettleMs, emptyReplyWaitMs, ...runtime }) => {
+    }, async ({ text, timeoutMs, lang, sessionId, requestId, context, replySettleMs, emptyReplyWaitMs, sttLang, pipeline, location, includeAudio, ...runtime }) => {
         return withRuntimeClient(runtime, async (client, signal) => {
             const builtContext = context ? buildClientContext({}, context) : undefined;
             const reply = await client.ask(text, {
@@ -1404,10 +1402,12 @@ export function createServer() {
                 sessionId,
                 requestId,
                 context: builtContext,
+                sttLang, pipeline, location: location ? buildLocation(location) : undefined,
                 replySettleMs,
                 emptyReplyWaitMs,
             });
-            return jsonContent(redactSecrets(summarizeReply(reply)));
+            const output = runtimeReplyContent(reply, includeAudio);
+            return { content: [...jsonContent(redactSecrets(output.summary)).content, ...output.clips] };
         });
     });
     registerThalovantTool(server, "thalovant_query", {
@@ -1417,6 +1417,7 @@ export function createServer() {
             ...runtimeAuthSchema,
             text: z.string().trim().min(1).max(20_000),
             timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
+            includeAudio: z.boolean().default(false).describe("Include bounded embedded skill clips as MCP audio/resources."),
             lang: z.string().min(1).optional(),
             sessionId: z.string().min(1).optional(),
             requestId: z.string().min(1).optional(),
@@ -1425,14 +1426,15 @@ export function createServer() {
             replySettleMs: z.number().int().min(0).max(10_000).optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, async ({ text, timeoutMs, lang, sessionId, requestId, queryId, context, replySettleMs, ...runtime }) => {
+    }, async ({ text, timeoutMs, lang, sessionId, requestId, queryId, context, replySettleMs, includeAudio, ...runtime }) => {
         return withRuntimeClient(runtime, async (client, signal) => {
             const reply = await client.query(text, {
                 signal,
                 timeoutMs: clampTimeout(timeoutMs), lang, sessionId, requestId, queryId,
                 context: context ? buildClientContext({}, context) : undefined, replySettleMs,
             });
-            return jsonContent(redactSecrets(summarizeReply(reply)));
+            const output = runtimeReplyContent(reply, includeAudio);
+            return { content: [...jsonContent(redactSecrets(output.summary)).content, ...output.clips] };
         });
     });
     registerThalovantTool(server, "thalovant_send_action", {
@@ -2030,7 +2032,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_get_runtime_group_config", {
         title: "Get Runtime Group Config",
-        description: "Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. Read this before thalovant_update_runtime_group_config so you know what the merge will land on.",
+        description: "Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. The revision returned by this call is used by safe configuration merges.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
@@ -2046,23 +2048,24 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_update_runtime_group_config", {
         title: "Update Runtime Group Config",
-        description: "Merge runtime configuration into a Thalovant runtime group. The API MERGES config into the stored configuration rather than replacing it, and marks the group pending so the runtime operator reconciles the change. personas, when provided, is REPLACED wholesale rather than merged; omit it to leave stored personas untouched. Requires the hubs:write scope and a paid plan.",
+        description: "Merge runtime configuration into a Thalovant runtime group. The SDK reads and deep-merges config, then writes with a revision precondition. Only explicit HTTP 412 conflicts retry, at most three attempts; older APIs fail before a write. Set merge=false for explicit unconditional replacement. personas, when provided, is REPLACED wholesale rather than merged; omit it to leave stored personas untouched. Requires hubs:read and paid hubs:write for merging; replacement needs paid hubs:write.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            merge: z.boolean().default(true).describe("False explicitly replaces the full configuration without a revision precondition."),
             config: jsonRecordSchema.describe("Configuration object merged into the stored configuration. Required."),
             personas: jsonRecordSchema.optional().describe("Replaces the stored personas outright. Left untouched when omitted."),
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ runtimeGroupId, config, personas, ...auth }) => {
+    }, async ({ runtimeGroupId, config, personas, merge, ...auth }) => {
         const api = await createControlPlane(auth);
         ensureAuthenticated(api);
-        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroupConfig(runtimeGroupId, config, { personas }))));
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroupConfig(runtimeGroupId, config, { personas, merge }))));
     });
     registerThalovantTool(server, "thalovant_release_runtime_group", {
         title: "Release Runtime Group",
@@ -2152,9 +2155,20 @@ export function createServer() {
         await callControlPlane("write", () => api.uninstallRuntimeGroupSkill(runtimeGroupId, skillId));
         return textContent("Runtime group skill uninstalled.");
     });
+    registerThalovantTool(server, "thalovant_list_hub_skill_history", {
+        title: "List Hub Skill History",
+        description: "Read newest-first skill events and operations for the runtime group attached to a hub. This history is shared by all hubs using that runtime. Requires hubs:inspect (hubs:read implies it); restricted tokens must cover all served hubs. Returns event/operation kind, timestamps, versions, actors and outcome fields. No changes are made.",
+        inputSchema: { ...controlPlaneSchema, hubId: z.string().uuid().describe("Hub UUID (not the slug)."), limit: z.number().int().min(1).max(200).default(50) },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ hubId, limit, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        throwIfRuntimeCancelled(requestContext.getStore()?.signal);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.listHubSkillHistory(hubId, { limit }))));
+    });
     registerThalovantTool(server, "thalovant_list_hub_skills", {
         title: "List Hub Skills",
-        description: "List the skills installed on ONE Thalovant hub. Returns the whole envelope: hub_id, runtime_group_id, observed_at, source, the runtime's phase and message, and data — one row per skill with version, version_pin, installed_version, observed_version, previous_version, latest_version, available_version, update_available, changelog, active, state (pending, installed, failed, removing, drifted, quarantined, unmanaged; a change in progress shows as pending), the runtime's last error and last_transition_at. This is per-hub, not the runtime group's skill set: a hub can start with an empty data array and gain skills one at a time with thalovant_install_hub_skill. hubId must be the hub UUID — the authenticated hub routes reject slugs; a hub with no runtime group attached fails 404 with code hub_without_runtime_group. Requires the hubs:inspect scope (hubs:read implies it); hub-restricted tokens only see the hubs in their allowlist.",
+        description: "List the skills installed on the runtime group attached to a Thalovant hub. Returns the whole envelope: hub_id, runtime_group_id, observed_at, source, the runtime's phase and message, and data — one row per skill with version, version_pin, installed_version, observed_version, previous_version, latest_version, available_version, update_available, changelog, active, state (pending, installed, failed, removing, drifted, quarantined, unmanaged; a change in progress shows as pending), the runtime's last error and last_transition_at. The hub UUID selects its attached runtime group. Skills and changes are shared by every hub using that group; restricted tokens must cover all served hubs. hubId must be the hub UUID — the authenticated hub routes reject slugs; a hub with no runtime group attached fails 404 with code hub_without_runtime_group. Requires the hubs:inspect scope (hubs:read implies it); hub-restricted tokens only see the hubs in their allowlist.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID (not the slug)."),
@@ -2168,7 +2182,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_install_hub_skill", {
         title: "Install Hub Skill",
-        description: "Install a skill on ONE Thalovant hub (not a runtime group or skill set). The change applies live on the hub in about 15 seconds, with no hub restart; a hub may start with no skills and gain them one at a time. Discover the skill name with thalovant_list_marketplace_skills. The API answers 202 with an operation_id and state \"installing\": pass wait: true to poll the operation until it converges (state \"installed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. The 202 body also carries hub_id, runtime_group_id and previous_version. Installing a skill that is already installed at ANOTHER version performs an update; the SAME version fails 409 with code skill_version_already_installed. Fails 404 with code hub_without_runtime_group when the hub has no runtime group attached yet, and 422 when \"latest\" cannot be resolved or the version string is invalid. hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. Hub-restricted tokens may only act on the hubs in their allowlist.",
+        description: "Install a skill on the runtime group attached to a Thalovant hub. All hubs sharing that runtime group are affected. The change applies live on the hub in about 15 seconds, with no hub restart; a hub may start with no skills and gain them one at a time. Discover the skill name with thalovant_list_marketplace_skills. The API answers 202 with an operation_id and state \"installing\": pass wait: true to poll the operation until it converges (state \"installed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. The 202 body also carries hub_id, runtime_group_id and previous_version. Installing a skill that is already installed at ANOTHER version performs an update; the SAME version fails 409 with code skill_version_already_installed. Fails 404 with code hub_without_runtime_group when the hub has no runtime group attached yet, and 422 when \"latest\" cannot be resolved or the version string is invalid. hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. A hub-restricted token must cover every hub sharing the affected runtime group.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID (not the slug)."),
@@ -2194,7 +2208,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_update_hub_skill", {
         title: "Update Hub Skill",
-        description: "Move a skill already installed on ONE Thalovant hub to a specific version (not a runtime group or skill set). The change applies live on the hub in about 15 seconds, with no hub restart. version is required — read the current version and latest_version from thalovant_list_hub_skills. The API answers 202 with an operation_id, hub_id, runtime_group_id, previous_version and state \"updating\": pass wait: true to poll the operation until it converges (state \"installed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. Fails 404 when the skill is not installed on the hub (code hub_without_runtime_group when the hub has no runtime group), 409 with code skill_version_already_installed when it is already at that version, and 422 for an invalid version. hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. Hub-restricted tokens may only act on the hubs in their allowlist.",
+        description: "Move a skill already installed on the runtime group attached to a Thalovant hub to a specific version (not a runtime group or skill set). The change applies live on the hub in about 15 seconds, with no hub restart. version is required — read the current version and latest_version from thalovant_list_hub_skills. The API answers 202 with an operation_id, hub_id, runtime_group_id, previous_version and state \"updating\": pass wait: true to poll the operation until it converges (state \"installed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. Fails 404 when the skill is not installed on the hub (code hub_without_runtime_group when the hub has no runtime group), 409 with code skill_version_already_installed when it is already at that version, and 422 for an invalid version. hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. A hub-restricted token must cover every hub sharing the affected runtime group.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID (not the slug)."),
@@ -2218,7 +2232,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_remove_hub_skill", {
         title: "Remove Hub Skill",
-        description: "Remove one skill from ONE Thalovant hub (not a runtime group or skill set). Only the named skill is removed; the hub and its other skills are untouched, and the change applies live on the hub in about 15 seconds with no hub restart. The API answers 202 with an operation_id, hub_id, runtime_group_id, previous_version (version is null) and state \"removing\": pass wait: true to poll the operation until it converges (state \"removed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. Fails 404 when the skill is not installed on the hub (code hub_without_runtime_group when the hub has no runtime group). hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. Hub-restricted tokens may only act on the hubs in their allowlist.",
+        description: "Remove one skill from the runtime group attached to a Thalovant hub. Every hub sharing the runtime loses this skill; other skill attachments are unchanged, and the change applies live on the hub in about 15 seconds with no hub restart. The API answers 202 with an operation_id, hub_id, runtime_group_id, previous_version (version is null) and state \"removing\": pass wait: true to poll the operation until it converges (state \"removed\", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. Fails 404 when the skill is not installed on the hub (code hub_without_runtime_group when the hub has no runtime group). hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. A hub-restricted token must cover every hub sharing the affected runtime group.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z.string().min(1).describe("Hub UUID (not the slug)."),

package/dist/reply-output.d.ts

@@ -0,0 +1,45 @@
+import type { ThalovantReply } from "@thalovant/sdk";
+/** Keep embedded skill bytes out of the language model's text context. */
+export declare function runtimeReplyContent(reply: ThalovantReply, includeAudio?: boolean): {
+    summary: {
+        text: string;
+        displayText: string;
+        utterances: string[];
+        handled: boolean;
+        ok: boolean;
+        sessionId: string | undefined;
+        requestId: string | undefined;
+        lang: string | undefined;
+        hasAudio: boolean;
+        droppedMedia: number;
+        displayItems: import("@thalovant/sdk").ThalovantDisplayItem[];
+        events: {
+            data: {
+                [x: string]: unknown;
+            };
+        }[];
+        media: {
+            eventIndex: number;
+            byteLength?: number;
+            mimeType?: string;
+            error?: string;
+        }[];
+        failureEvent: {
+            data: {
+                [x: string]: unknown;
+            };
+        } | undefined;
+    };
+    clips: ({
+        type: "audio";
+        data: string;
+        mimeType: string;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            mimeType: string;
+            blob: string;
+        };
+    })[];
+};

package/dist/reply-output.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+function eventSummary(event) {
+    const { binary_data: _encoded, ...data } = event.data;
+    return { ...event.asObject(), data };
+}
+/** Keep embedded skill bytes out of the language model's text context. */
+export function runtimeReplyContent(reply, includeAudio = false) {
+    const clips = [];
+    const media = [];
+    const events = reply.events.map((event, eventIndex) => {
+        const output = eventSummary(event);
+        if (!event.isAudio)
+            return output;
+        try {
+            const bytes = Buffer.from(event.audioBytes());
+            const mimeType = bytes.subarray(0, 4).toString() === "RIFF" && bytes.subarray(8, 12).toString() === "WAVE" ? "audio/wav"
+                : bytes.subarray(0, 4).toString() === "OggS" ? "audio/ogg"
+                    : bytes.subarray(0, 4).toString() === "fLaC" ? "audio/flac"
+                        : bytes.subarray(0, 3).toString() === "ID3" ? "audio/mpeg" : "application/octet-stream";
+            media.push({ eventIndex, byteLength: bytes.length, mimeType });
+            if (includeAudio) {
+                const encoded = bytes.toString("base64");
+                clips.push(mimeType.startsWith("audio/") ? { type: "audio", data: encoded, mimeType } : {
+                    type: "resource", resource: { uri: `thalovant-audio://sha256/${createHash("sha256").update(bytes).digest("hex")}`, mimeType, blob: encoded },
+                });
+            }
+        }
+        catch {
+            media.push({ eventIndex, error: "Missing, invalid or oversized embedded audio." });
+        }
+        return output;
+    });
+    return { summary: {
+            text: reply.text, displayText: reply.displayText, utterances: reply.utterances,
+            handled: reply.handled, ok: reply.ok, sessionId: reply.sessionId, requestId: reply.requestId,
+            lang: reply.lang, hasAudio: reply.hasAudio ?? false, droppedMedia: reply.droppedMedia ?? 0,
+            displayItems: reply.displayItems({ maxTextChars: 1_000 }), events, media,
+            // A failure reference must not bypass text sanitization or add a clip
+            // outside the SDK's admitted event sequence and aggregate media budget.
+            failureEvent: reply.failureEvent ? eventSummary(reply.failureEvent) : undefined,
+        }, clips };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.24",
+  "version": "0.3.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.3.16",
+    "@thalovant/sdk": "^0.5.1",
     "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.1.24",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.1.24",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.1.24",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.3.0",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"