@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/security/openai-device-auth.ts

@@ -0,0 +1,364 @@
+/**
+ * OpenAI Codex device-code authorization.
+ *
+ * OpenAI's Codex sign-in uses a bespoke device-authorization API rather than
+ * RFC 8628. The daemon asks for a short user code, the user types it at
+ * `https://auth.openai.com/codex/device`, and the poll endpoint answers with an
+ * OAuth authorization code plus the PKCE pair minted alongside it. The caller
+ * exchanges that pair at the normal token endpoint, so the resulting tokens are
+ * identical to the browser redirect flow's.
+ *
+ * The account must have "Enable device code authorization for Codex" turned on
+ * in ChatGPT security settings. When it is off the poll never succeeds: it
+ * either stays pending until the code expires or answers with a distinct error
+ * code, both of which surface as a `DeviceAuthError`.
+ */
+
+import { getLogger } from "../util/logger.js";
+import type { OAuth2Config, OAuth2FlowResult } from "./oauth2.js";
+import { exchangeCodeForTokens } from "./oauth2.js";
+
+const log = getLogger("openai-device-auth");
+
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+
+export const OPENAI_DEVICE_AUTH_USERCODE_URL =
+  "https://auth.openai.com/api/accounts/deviceauth/usercode";
+
+export const OPENAI_DEVICE_AUTH_TOKEN_URL =
+  "https://auth.openai.com/api/accounts/deviceauth/token";
+
+/** Page where the user types the short code. */
+export const OPENAI_DEVICE_VERIFICATION_URL =
+  "https://auth.openai.com/codex/device";
+
+/** Redirect URI the device-issued authorization code is bound to. */
+export const OPENAI_DEVICE_REDIRECT_URI =
+  "https://auth.openai.com/deviceauth/callback";
+
+/** Fallback poll interval when the server omits or garbles `interval`. */
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+
+/** Hard ceiling on a device authorization, regardless of `expires_at`. */
+export const OPENAI_DEVICE_AUTH_MAX_LIFETIME_MS = 15 * 60 * 1000;
+
+/** Error code the poll endpoint returns while the user has not yet approved. */
+const AUTHORIZATION_PENDING_CODE = "deviceauth_authorization_pending";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export class DeviceAuthError extends Error {
+  /**
+   * Machine-readable failure code: the provider's `error.code` when it sends
+   * one, otherwise a locally assigned code (`expired_token`, `request_failed`,
+   * `aborted`).
+   */
+  readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "DeviceAuthError";
+    this.code = code;
+  }
+}
+
+/** A minted device authorization, before the user has approved it. */
+export interface DeviceAuthRequest {
+  deviceAuthId: string;
+  /** Short code the user types at `verificationUrl`. */
+  userCode: string;
+  verificationUrl: string;
+  /** ISO-8601 instant after which the code stops being accepted. */
+  expiresAt: string;
+  intervalSeconds: number;
+}
+
+/** The PKCE-bound authorization code the poll endpoint hands back. */
+export interface DeviceAuthCode {
+  authorizationCode: string;
+  codeVerifier: string;
+  codeChallenge?: string;
+}
+
+export interface DeviceAuthOptions {
+  /** Injectable `fetch`, for tests. */
+  fetchImpl?: typeof fetch;
+  /** Injectable delay between polls, for tests. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable clock, for tests. */
+  now?: () => number;
+  signal?: AbortSignal;
+}
+
+// ---------------------------------------------------------------------------
+// Step 1: mint a user code
+// ---------------------------------------------------------------------------
+
+export async function requestDeviceCode(
+  clientId: string,
+  options: DeviceAuthOptions = {},
+): Promise<DeviceAuthRequest> {
+  const doFetch = options.fetchImpl ?? fetch;
+
+  let response: Response;
+  try {
+    response = await doFetch(OPENAI_DEVICE_AUTH_USERCODE_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({ client_id: clientId }),
+      signal: options.signal,
+    });
+  } catch (err) {
+    throw new DeviceAuthError(
+      `Could not reach the device authorization endpoint: ${errorMessage(err)}`,
+      "request_failed",
+    );
+  }
+
+  if (!response.ok) {
+    const { code, message } = await readErrorBody(response);
+    throw new DeviceAuthError(
+      message ??
+        `Device authorization request failed (HTTP ${response.status})`,
+      code ?? "request_failed",
+    );
+  }
+
+  const data = (await response.json()) as Record<string, unknown>;
+  const deviceAuthId = asString(data.device_auth_id);
+  const userCode = asString(data.user_code);
+  if (!deviceAuthId || !userCode) {
+    throw new DeviceAuthError(
+      "Device authorization response is missing a device id or user code.",
+      "request_failed",
+    );
+  }
+
+  const expiresAt =
+    asString(data.expires_at) ??
+    new Date(
+      (options.now?.() ?? Date.now()) + OPENAI_DEVICE_AUTH_MAX_LIFETIME_MS,
+    ).toISOString();
+
+  return {
+    deviceAuthId,
+    userCode,
+    verificationUrl: OPENAI_DEVICE_VERIFICATION_URL,
+    expiresAt,
+    intervalSeconds: parseIntervalSeconds(data.interval),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: poll until the user approves
+// ---------------------------------------------------------------------------
+
+/**
+ * Poll until the user approves the code, the code expires, or the provider
+ * reports a non-pending failure.
+ *
+ * The poll answers 403 (and occasionally 404) while approval is outstanding, so
+ * those statuses are only fatal when the body names an error code other than
+ * `deviceauth_authorization_pending`. Transport failures and 5xx/429 responses
+ * are retried until the deadline.
+ */
+export async function pollForAuthorizationCode(
+  request: DeviceAuthRequest,
+  options: DeviceAuthOptions = {},
+): Promise<DeviceAuthCode> {
+  const doFetch = options.fetchImpl ?? fetch;
+  const doSleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? (() => Date.now());
+
+  const intervalMs = request.intervalSeconds * 1000;
+  const deadline = resolveDeadline(request.expiresAt, now());
+
+  while (now() < deadline) {
+    assertNotAborted(options.signal);
+
+    let response: Response | undefined;
+    try {
+      response = await doFetch(OPENAI_DEVICE_AUTH_TOKEN_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          device_auth_id: request.deviceAuthId,
+          user_code: request.userCode,
+        }),
+        signal: options.signal,
+      });
+    } catch (err) {
+      assertNotAborted(options.signal);
+      log.warn({ err: errorMessage(err) }, "Device auth poll failed, retrying");
+    }
+
+    if (response?.ok) {
+      const data = (await response.json()) as Record<string, unknown>;
+      const authorizationCode = asString(data.authorization_code);
+      const codeVerifier = asString(data.code_verifier);
+      if (!authorizationCode || !codeVerifier) {
+        throw new DeviceAuthError(
+          "Device authorization succeeded but returned no authorization code.",
+          "request_failed",
+        );
+      }
+      log.info("OpenAI device authorization approved");
+      const result: DeviceAuthCode = { authorizationCode, codeVerifier };
+      const codeChallenge = asString(data.code_challenge);
+      if (codeChallenge) {
+        result.codeChallenge = codeChallenge;
+      }
+      return result;
+    }
+
+    if (response && !isRetryableStatus(response.status)) {
+      const { code, message } = await readErrorBody(response);
+      // A pending approval answers 403/404 with the pending code; anything else
+      // is terminal, including the error raised when device-code authorization
+      // is disabled for the account.
+      if (code !== AUTHORIZATION_PENDING_CODE && (code || message)) {
+        throw new DeviceAuthError(
+          message ?? `Device authorization failed (HTTP ${response.status})`,
+          code ?? "request_failed",
+        );
+      }
+    }
+
+    await doSleep(intervalMs);
+  }
+
+  assertNotAborted(options.signal);
+  throw new DeviceAuthError(
+    "The device code expired before the sign-in was approved.",
+    "expired_token",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Step 3: exchange the authorization code
+// ---------------------------------------------------------------------------
+
+/**
+ * Run steps 2 and 3: wait for approval, then exchange the device-issued
+ * authorization code and its PKCE verifier for OAuth tokens.
+ *
+ * The signal reaches the exchange too, and is checked once more after it
+ * returns: a cancellation that lands while the tokens are in flight must not
+ * hand the caller a set of credentials to store.
+ */
+export async function completeDeviceAuth(
+  config: OAuth2Config,
+  request: DeviceAuthRequest,
+  options: DeviceAuthOptions = {},
+): Promise<OAuth2FlowResult> {
+  const { authorizationCode, codeVerifier } = await pollForAuthorizationCode(
+    request,
+    options,
+  );
+
+  const result = await exchangeCodeForTokens(
+    config,
+    authorizationCode,
+    OPENAI_DEVICE_REDIRECT_URI,
+    codeVerifier,
+    undefined,
+    { signal: options.signal },
+  );
+  assertNotAborted(options.signal);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** `interval` arrives as a string of seconds; fall back when it is unusable. */
+function parseIntervalSeconds(raw: unknown): number {
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_POLL_INTERVAL_SECONDS;
+  }
+  return parsed;
+}
+
+/** Stop at `expires_at`, never later than the hard lifetime ceiling. */
+function resolveDeadline(expiresAt: string, startedAt: number): number {
+  const ceiling = startedAt + OPENAI_DEVICE_AUTH_MAX_LIFETIME_MS;
+  const parsed = Date.parse(expiresAt);
+  if (!Number.isFinite(parsed)) {
+    return ceiling;
+  }
+  return Math.min(parsed, ceiling);
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * Pull `{ error: { code, message } }` off a failure body. Both fields are
+ * optional: an unparseable body reads as a transient failure so the caller
+ * keeps polling.
+ */
+async function readErrorBody(
+  response: Response,
+): Promise<{ code?: string; message?: string }> {
+  const raw = await response.text().catch(() => "");
+  if (!raw) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const error = parsed.error;
+    if (error && typeof error === "object") {
+      const nested = error as Record<string, unknown>;
+      const result: { code?: string; message?: string } = {};
+      const code = asString(nested.code);
+      if (code) {
+        result.code = code;
+      }
+      const message = asString(nested.message);
+      if (message) {
+        result.message = message;
+      }
+      return result;
+    }
+    const code = asString(error);
+    return code ? { code } : {};
+  } catch {
+    return {};
+  }
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function assertNotAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw new DeviceAuthError("Device authorization was cancelled.", "aborted");
+  }
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    if (typeof timer === "object" && "unref" in timer) {
+      timer.unref();
+    }
+  });
+}

package/src/security/secure-keys.ts

@@ -156,6 +156,21 @@ export function setCesClient(client: CesClient | undefined): void {
     "CES client updated; resetting resolved credential backend cache",
   );
   _cesClientListener?.(client);
+  void attachCredentialRecordBackend(client);
+}
+
+async function attachCredentialRecordBackend(
+  client: CesClient | undefined,
+): Promise<void> {
+  const { CesRpcRecordBackend } = await import("./ces-rpc-record-backend.js");
+  const { setCredentialRecordBackend } = await import(
+    "../tools/credentials/metadata-store.js"
+  );
+  if (!client) {
+    setCredentialRecordBackend(undefined);
+    return;
+  }
+  setCredentialRecordBackend(new CesRpcRecordBackend(client));
 }
 
 /**

package/src/skills/available-skills.ts

@@ -1,6 +1,10 @@
 import { getConfig } from "../config/loader.js";
 import type { SkillSource } from "../config/skills.js";
 import type { SkillInstallMeta } from "./install-meta.js";
+import {
+  isSkillCompatibleWithPlatform,
+  type SkillPlatform,
+} from "./platform-compatibility.js";
 
 /**
  * Plugin-facing read API over the skill surface: the locally installed
@@ -28,6 +32,8 @@ export interface ResolvedSkillEntry {
   avoidWhen?: string[];
   /** True when the skill is pinned into the memory selector pool every turn. */
   alwaysCandidate?: boolean;
+  /** Host operating systems on which this skill may be used. */
+  platforms?: SkillPlatform[];
   /** True for locally installed skills; false for remote catalog entries. */
   installed: boolean;
   /** Where the installed skill comes from. Unset for remote catalog entries. */
@@ -77,6 +83,7 @@ export async function listInstalledSkills(): Promise<ResolvedSkillEntry[]> {
       activationHints: summary.activationHints,
       avoidWhen: summary.avoidWhen,
       alwaysCandidate: summary.alwaysCandidate,
+      platforms: summary.platforms,
       installed: true,
       source: summary.source,
       state: stateById.get(summary.id) ?? "unavailable",
@@ -121,14 +128,16 @@ export async function listCatalogSkills(): Promise<ResolvedSkillEntry[]> {
       typeof flagKey === "string" &&
       flagKey.length > 0 &&
       !isAssistantFeatureFlagEnabled(flagKey, config);
+    const incompatible = !isSkillCompatibleWithPlatform(entry);
     return {
       id: entry.id,
       displayName: entry.metadata?.vellum?.["display-name"] ?? entry.name,
       description: entry.description,
       activationHints: entry.metadata?.vellum?.["activation-hints"],
       avoidWhen: entry.metadata?.vellum?.["avoid-when"],
+      platforms: entry.platforms,
       installed: false,
-      state: gated ? "unavailable" : "available",
+      state: gated || incompatible ? "unavailable" : "available",
     };
   });
 }

package/src/skills/catalog-install.ts

@@ -19,6 +19,12 @@ import { loadSkillCatalog } from "../config/skills.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
 import { computeSkillHash, writeInstallMeta } from "./install-meta.js";
+import {
+  isSkillCompatibleWithPlatform,
+  normalizeSkillPlatforms,
+  type SkillPlatform,
+  skillPlatformUnavailableMessage,
+} from "./platform-compatibility.js";
 
 const log = getLogger("catalog-install");
 
@@ -33,6 +39,7 @@ export interface CatalogSkill {
   includes?: string[];
   version?: string;
   updatedAt?: string;
+  platforms?: SkillPlatform[];
   metadata?: {
     icon?: string;
     emoji?: string;
@@ -42,6 +49,7 @@ export interface CatalogSkill {
       "avoid-when"?: string[];
       "feature-flag"?: string;
       category?: string;
+      platforms?: SkillPlatform[];
     };
   };
 }
@@ -111,6 +119,7 @@ interface RawCatalogEntry {
   updatedAt?: unknown;
   display_name?: unknown;
   category?: unknown;
+  platforms?: unknown;
   updated_at?: unknown;
   metadata?: CatalogSkill["metadata"];
 }
@@ -144,6 +153,9 @@ function normalizeCatalogEntry(raw: unknown): CatalogSkill | null {
   const displayName = nested?.["display-name"] ?? asStr(entry.display_name);
   const icon = asStr(entry.icon) ?? asStr(entry.metadata?.icon);
   const updatedAt = asStr(entry.updatedAt) ?? asStr(entry.updated_at);
+  const platforms = normalizeSkillPlatforms(
+    nested?.platforms ?? entry.platforms,
+  );
 
   return {
     id,
@@ -154,6 +166,7 @@ function normalizeCatalogEntry(raw: unknown): CatalogSkill | null {
     ...(entry.includes ? { includes: entry.includes } : {}),
     ...(entry.version ? { version: entry.version } : {}),
     ...(updatedAt ? { updatedAt } : {}),
+    ...(platforms ? { platforms } : {}),
     metadata: {
       ...entry.metadata,
       ...(icon ? { icon } : {}),
@@ -161,6 +174,7 @@ function normalizeCatalogEntry(raw: unknown): CatalogSkill | null {
         ...nested,
         ...(displayName ? { "display-name": displayName } : {}),
         ...(category ? { category } : {}),
+        ...(platforms ? { platforms } : {}),
       },
     },
   };
@@ -610,7 +624,8 @@ export async function resolveCatalog(
 /**
  * Attempt to find and install a skill from the first-party catalog.
  * Returns true if the skill was installed, false if not found in catalog.
- * Throws on install failures (network, filesystem, etc).
+ * Throws when the skill is unsupported on this host or on install failures
+ * (network, filesystem, etc).
  *
  * When `catalog` is provided it is used directly, avoiding a redundant
  * network fetch — pass a pre-resolved catalog when calling in a loop.
@@ -639,6 +654,9 @@ export async function autoInstallFromCatalog(
   if (!entry) {
     return false;
   }
+  if (!isSkillCompatibleWithPlatform(entry)) {
+    throw new Error(skillPlatformUnavailableMessage(skillId, entry));
+  }
 
   // If the skill already exists on disk, reuse it instead of attempting a
   // fresh install that would fail.

package/src/skills/inline-command-runner.ts

@@ -25,6 +25,10 @@ import { spawn } from "node:child_process";
 
 import { buildSanitizedEnv } from "../tools/terminal/safe-env.js";
 import { stripAnsiSequences } from "../util/ansi.js";
+import {
+  buildShellInvocation,
+  terminateProcessTree,
+} from "../util/host-process.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("inline-command-runner");
@@ -99,7 +103,7 @@ export async function runInlineCommand(
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const maxChars = options?.maxOutputChars ?? MAX_OUTPUT_CHARS;
 
-  const wrapped = { command: "bash", args: ["-c", "--", command] };
+  const wrapped = buildShellInvocation(command);
 
   // Build a minimal, sanitized environment. Explicitly exclude gateway URL,
   // workspace dir, and data dir since inline commands have no business calling
@@ -135,7 +139,7 @@ export async function runInlineCommand(
 
     const timer = setTimeout(() => {
       timedOut = true;
-      child.kill("SIGKILL");
+      terminateProcessTree(child);
     }, timeoutMs);
 
     child.stdout!.on("data", (data: Buffer) => {

package/src/skills/platform-compatibility.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  filterSkillsByPlatform,
+  isSkillCompatibleWithPlatform,
+  normalizeSkillPlatforms,
+  skillPlatformForNodePlatform,
+} from "./platform-compatibility.js";
+
+describe("skill platform compatibility", () => {
+  test("maps Node platforms to skill platform names", () => {
+    expect(skillPlatformForNodePlatform("darwin")).toBe("macos");
+    expect(skillPlatformForNodePlatform("win32")).toBe("windows");
+    expect(skillPlatformForNodePlatform("linux")).toBe("linux");
+    expect(skillPlatformForNodePlatform("freebsd")).toBeNull();
+  });
+
+  test("treats missing platform metadata as portable", () => {
+    expect(isSkillCompatibleWithPlatform({}, "win32")).toBe(true);
+    expect(isSkillCompatibleWithPlatform({}, "linux")).toBe(true);
+  });
+
+  test("matches declared host platforms", () => {
+    const skill = { platforms: ["macos", "linux"] as const };
+    expect(isSkillCompatibleWithPlatform(skill, "darwin")).toBe(true);
+    expect(isSkillCompatibleWithPlatform(skill, "linux")).toBe(true);
+    expect(isSkillCompatibleWithPlatform(skill, "win32")).toBe(false);
+  });
+
+  test("filters incompatible skills from offer surfaces", () => {
+    const skills = [
+      { id: "portable" },
+      { id: "mac-only", platforms: ["macos"] as const },
+      { id: "windows-only", platforms: ["windows"] as const },
+    ];
+
+    expect(
+      filterSkillsByPlatform(skills, "win32").map((skill) => skill.id),
+    ).toEqual(["portable", "windows-only"]);
+  });
+
+  test("normalizes valid unique metadata values", () => {
+    expect(normalizeSkillPlatforms(["windows", "windows", "linux"])).toEqual([
+      "windows",
+      "linux",
+    ]);
+    expect(normalizeSkillPlatforms(["android", 42])).toBeUndefined();
+  });
+});

package/src/skills/platform-compatibility.ts

@@ -0,0 +1,65 @@
+export const SKILL_PLATFORM_VALUES = ["macos", "windows", "linux"] as const;
+
+export type SkillPlatform = (typeof SKILL_PLATFORM_VALUES)[number];
+
+export interface PlatformScopedSkill {
+  platforms?: readonly SkillPlatform[];
+}
+
+export function normalizeSkillPlatforms(
+  value: unknown,
+): SkillPlatform[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const platforms = [
+    ...new Set(
+      value.filter((platform): platform is SkillPlatform =>
+        (SKILL_PLATFORM_VALUES as readonly unknown[]).includes(platform),
+      ),
+    ),
+  ];
+  return platforms.length > 0 ? platforms : undefined;
+}
+
+export function skillPlatformForNodePlatform(
+  platform: NodeJS.Platform,
+): SkillPlatform | null {
+  if (platform === "darwin") {
+    return "macos";
+  }
+  if (platform === "win32") {
+    return "windows";
+  }
+  if (platform === "linux") {
+    return "linux";
+  }
+  return null;
+}
+
+export function isSkillCompatibleWithPlatform(
+  skill: PlatformScopedSkill,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (!skill.platforms || skill.platforms.length === 0) {
+    return true;
+  }
+  const skillPlatform = skillPlatformForNodePlatform(platform);
+  return skillPlatform !== null && skill.platforms.includes(skillPlatform);
+}
+
+export function filterSkillsByPlatform<T extends PlatformScopedSkill>(
+  skills: readonly T[],
+  platform: NodeJS.Platform = process.platform,
+): T[] {
+  return skills.filter((skill) =>
+    isSkillCompatibleWithPlatform(skill, platform),
+  );
+}
+
+export function skillPlatformUnavailableMessage(
+  skillId: string,
+  skill: PlatformScopedSkill,
+): string {
+  return `Skill "${skillId}" is unavailable on this operating system. Supported platforms: ${(skill.platforms ?? []).join(", ")}.`;
+}

package/src/skills/tool-manifest.ts

@@ -1,9 +1,11 @@
 import { readFileSync } from "node:fs";
 
+import { CLIENT_OS_VALUES, type ClientOs } from "../channels/types.js";
 import type { SkillToolEntry, SkillToolManifest } from "../config/skills.js";
 
 const VALID_RISK_LEVELS = new Set(["low", "medium", "high"]);
 const VALID_EXECUTION_TARGETS = new Set(["host", "sandbox"]);
+const VALID_CLIENT_OS_VALUES = new Set<string>(CLIENT_OS_VALUES);
 
 /**
  * Parse and validate a raw TOOLS.json payload into a typed SkillToolManifest.
@@ -137,6 +139,23 @@ function parseToolEntry(raw: unknown, prefix: string): SkillToolEntry {
   const execution_target =
     entry.execution_target as SkillToolEntry["execution_target"];
 
+  let supported_client_os: ClientOs[] | undefined;
+  if ("supported_client_os" in entry) {
+    if (
+      !Array.isArray(entry.supported_client_os) ||
+      entry.supported_client_os.length === 0 ||
+      entry.supported_client_os.some(
+        (value) =>
+          typeof value !== "string" || !VALID_CLIENT_OS_VALUES.has(value),
+      )
+    ) {
+      throw new Error(
+        `${prefix}: "supported_client_os" must be a non-empty array of known client OS values`,
+      );
+    }
+    supported_client_os = [...new Set(entry.supported_client_os as ClientOs[])];
+  }
+
   return {
     name,
     description,
@@ -145,6 +164,7 @@ function parseToolEntry(raw: unknown, prefix: string): SkillToolEntry {
     input_schema,
     executor,
     execution_target,
+    supported_client_os,
   };
 }