@vellumai/assistant 0.12.5 → 0.12.6-dev.202609292116.41f7caa

package/src/cli/lib/plugin-artifact.ts

@@ -52,21 +52,76 @@ const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
  * the digest must be canonical lowercase hex so client-side comparison is a
  * plain string equality with no normalization step.
  */
-const PluginArtifactSchema = z.object({
-  url: z
-    .string()
-    .url()
-    .refine((u) => u.startsWith("https://"), {
-      message: "artifact url must be an https:// URL",
-    }),
-  sha256: z
-    .string()
-    .regex(SHA256_HEX_RE, "artifact sha256 must be 64 lowercase hex chars"),
-  // Optional, non-critical metadata: a malformed label must never nullify an
-  // otherwise-valid `url` + `sha256`, so a wrong-typed value falls back to
-  // `undefined` rather than failing the whole descriptor.
-  label: z.string().optional().catch(undefined),
-});
+const PluginArtifactSchema = z
+  .object({
+    url: z
+      .string()
+      .url()
+      .refine((u) => u.startsWith("https://"), {
+        message: "artifact url must be an https:// URL",
+      }),
+    sha256: z
+      .string()
+      .regex(SHA256_HEX_RE, "artifact sha256 must be 64 lowercase hex chars"),
+    // Optional, non-critical metadata: a malformed label must never nullify an
+    // otherwise-valid `url` + `sha256`, so a wrong-typed value falls back to
+    // `undefined` rather than failing the whole descriptor.
+    label: z
+      .string()
+      .transform((label) => label.trim())
+      .optional()
+      .catch(undefined),
+  })
+  .transform(({ label, ...artifact }) =>
+    label ? { ...artifact, label } : artifact,
+  );
+
+/** Upper bound on `vellum.icon`, in Unicode code points. */
+const MAX_ICON_CODE_POINTS = 16;
+
+const PluginIconSchema = z
+  .string()
+  .transform((icon) => icon.trim())
+  .refine(
+    (icon) => {
+      const codePoints = [...icon].length;
+      return codePoints >= 1 && codePoints <= MAX_ICON_CODE_POINTS;
+    },
+    { message: "plugin icon must contain 1 to 16 Unicode code points" },
+  );
+
+const LicenseSchema = z
+  .union([
+    z.string(),
+    z.object({ type: z.string() }).transform(({ type }) => type),
+    z.undefined(),
+  ])
+  .catch(undefined);
+
+export const PluginPackageJsonSchema = z
+  .object({
+    name: z.string().optional().catch(undefined),
+    version: z.string().optional().catch(undefined),
+    description: z.string().optional().catch(undefined),
+    homepage: z.string().optional().catch(undefined),
+    license: LicenseSchema.optional(),
+    peerDependencies: z
+      .record(z.string(), z.string())
+      .optional()
+      .catch(undefined),
+    vellum: z
+      .object({
+        artifact: PluginArtifactSchema.optional().catch(undefined),
+        icon: PluginIconSchema.optional().catch(undefined),
+      })
+      .optional()
+      .catch(undefined),
+  })
+  .transform(({ vellum, ...packageJson }) => ({
+    ...packageJson,
+    artifact: vellum?.artifact,
+    icon: vellum?.icon,
+  }));
 
 /**
  * Read `vellum.artifact` from an already-parsed `package.json` value and
@@ -78,35 +133,10 @@ const PluginArtifactSchema = z.object({
 export function parsePluginArtifact(
   packageJson: unknown,
 ): PluginArtifact | null {
-  if (
-    typeof packageJson !== "object" ||
-    packageJson === null ||
-    Array.isArray(packageJson)
-  ) {
-    return null;
-  }
-  const vellum = (packageJson as Record<string, unknown>).vellum;
-  if (typeof vellum !== "object" || vellum === null || Array.isArray(vellum)) {
-    return null;
-  }
-  const artifact = (vellum as Record<string, unknown>).artifact;
-  const parsed = PluginArtifactSchema.safeParse(artifact);
-  if (!parsed.success) {
-    return null;
-  }
-  // A blank or whitespace-only label is treated as absent so it never
-  // invalidates an otherwise well-formed `url` + `sha256` descriptor.
-  const label = parsed.data.label?.trim();
-  return {
-    url: parsed.data.url,
-    sha256: parsed.data.sha256,
-    ...(label ? { label } : {}),
-  };
+  const parsed = PluginPackageJsonSchema.safeParse(packageJson);
+  return parsed.success ? (parsed.data.artifact ?? null) : null;
 }
 
-/** Upper bound on `vellum.icon`, in Unicode code points. */
-const MAX_ICON_CODE_POINTS = 16;
-
 /**
  * Read `vellum.icon` from an already-parsed `package.json` value and return
  * it only when it is a short, non-empty glyph (an emoji or similar). The
@@ -115,25 +145,6 @@ const MAX_ICON_CODE_POINTS = 16;
  * type, empty, or too long — yields `undefined` rather than throwing.
  */
 export function parsePluginIcon(packageJson: unknown): string | undefined {
-  if (
-    typeof packageJson !== "object" ||
-    packageJson === null ||
-    Array.isArray(packageJson)
-  ) {
-    return undefined;
-  }
-  const vellum = (packageJson as Record<string, unknown>).vellum;
-  if (typeof vellum !== "object" || vellum === null || Array.isArray(vellum)) {
-    return undefined;
-  }
-  const icon = (vellum as Record<string, unknown>).icon;
-  if (typeof icon !== "string") {
-    return undefined;
-  }
-  const trimmed = icon.trim();
-  const codePoints = [...trimmed].length;
-  if (codePoints < 1 || codePoints > MAX_ICON_CODE_POINTS) {
-    return undefined;
-  }
-  return trimmed;
+  const parsed = PluginPackageJsonSchema.safeParse(packageJson);
+  return parsed.success ? parsed.data.icon : undefined;
 }

package/src/cli/lib/plugin-catalog-visibility.ts

@@ -10,6 +10,7 @@ const MCP_CATALOG_QA_INTEGRATION_NAMES = new Set([
   "ramp",
   "semrush",
   "typeform",
+  "upwork",
 ]);
 
 export type PluginCatalogFeatureFlagResolver = (key: string) => boolean;

package/src/cli/lib/plugin-details.ts

@@ -32,15 +32,16 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import { readPluginManifest } from "../../util/plugin-manifest.js";
 import { readBundledPluginFile } from "./bundled-plugin-packages.js";
 import type { FetchLike } from "./fetch-like.js";
 import { sanitizePluginName } from "./install-from-github.js";
 import {
-  parsePluginArtifact,
-  parsePluginIcon,
   type PluginArtifact,
+  PluginPackageJsonSchema,
 } from "./plugin-artifact.js";
 import {
   findCatalogEntry,
@@ -61,12 +62,16 @@ import {
 const README_RE = /^readme(\.md|\.markdown)?$/i;
 
 /** Entry shape returned by the GitHub Contents API for a directory listing. */
-interface GitHubContentEntry {
-  readonly name: string;
-  readonly path: string;
-  readonly type: "file" | "dir" | "symlink" | "submodule";
-  readonly download_url: string | null;
-}
+const GitHubContentEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  type: z.enum(["file", "dir", "symlink", "submodule"]),
+  download_url: z.string().nullable(),
+});
+
+const GitHubContentListingSchema = z.array(GitHubContentEntrySchema);
+
+type GitHubContentEntry = z.infer<typeof GitHubContentEntrySchema>;
 
 /** The subset of `package.json` fields the detail view surfaces. */
 interface PluginManifestFields {
@@ -249,11 +254,14 @@ function readLocalPlugin(pluginsDir: string, name: string): LocalPlugin {
       manifest = parseManifest(readFileSync(packagePath, "utf8"));
     } else {
       const selected = readPluginManifest(target);
+      const parsedPackageJson = PluginPackageJsonSchema.safeParse(selected.raw);
       manifest = {
         version: selected.version ?? null,
         description: selected.description ?? null,
         homepage: selected.homepage ?? null,
-        license: normalizeLicense(selected.license),
+        license: parsedPackageJson.success
+          ? (parsedPackageJson.data.license ?? null)
+          : null,
         artifact: null,
         icon: null,
       };
@@ -365,11 +373,8 @@ async function listDirSafe(
     if (!res.ok) {
       return null;
     }
-    const body = (await res.json()) as unknown;
-    if (!Array.isArray(body)) {
-      return null;
-    }
-    return body as readonly GitHubContentEntry[];
+    const parsed = GitHubContentListingSchema.safeParse(await res.json());
+    return parsed.success ? parsed.data : null;
   } catch {
     return null;
   }
@@ -502,36 +507,16 @@ function safeParseManifest(raw: string): PluginManifestFields {
 
 /** Extract the surfaced fields from a `package.json` body. Throws on bad JSON. */
 function parseManifest(raw: string): PluginManifestFields {
-  const parsed: unknown = JSON.parse(raw);
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  const parsed = PluginPackageJsonSchema.safeParse(JSON.parse(raw));
+  if (!parsed.success) {
     return emptyManifest();
   }
-  const meta = parsed as Record<string, unknown>;
   return {
-    version: typeof meta.version === "string" ? meta.version : null,
-    description: typeof meta.description === "string" ? meta.description : null,
-    homepage: typeof meta.homepage === "string" ? meta.homepage : null,
-    license: normalizeLicense(meta.license),
-    artifact: parsePluginArtifact(parsed),
-    icon: parsePluginIcon(parsed) ?? null,
+    version: parsed.data.version ?? null,
+    description: parsed.data.description ?? null,
+    homepage: parsed.data.homepage ?? null,
+    license: parsed.data.license ?? null,
+    artifact: parsed.data.artifact ?? null,
+    icon: parsed.data.icon ?? null,
   };
 }
-
-/**
- * `package.json#license` is usually an SPDX string but the legacy object form
- * `{ "type": "MIT" }` still appears in the wild — surface its `type`.
- */
-function normalizeLicense(value: unknown): string | null {
-  if (typeof value === "string") {
-    return value;
-  }
-  if (
-    typeof value === "object" &&
-    value !== null &&
-    "type" in value &&
-    typeof (value as { type: unknown }).type === "string"
-  ) {
-    return (value as { type: string }).type;
-  }
-  return null;
-}

package/src/cli/lib/plugin-marketplace.ts

@@ -183,15 +183,13 @@ const fetchedMarketplaceManifestSchema = marketplaceManifestBaseSchema.extend({
   plugins: z.array(z.unknown()),
 });
 
+const marketplaceSourceDiscriminatorSchema = z.object({
+  source: z.object({ source: z.unknown() }),
+});
+
 function readSourceDiscriminator(entry: unknown): unknown {
-  if (typeof entry !== "object" || entry === null) {
-    return null;
-  }
-  const source = (entry as Record<string, unknown>).source;
-  if (typeof source !== "object" || source === null) {
-    return null;
-  }
-  return (source as Record<string, unknown>).source;
+  const parsed = marketplaceSourceDiscriminatorSchema.safeParse(entry);
+  return parsed.success ? parsed.data.source.source : null;
 }
 
 /** A single reviewed plugin entry. */

package/src/cli/lib/plugin-surfaces.ts

@@ -23,6 +23,8 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 /** A schedule the plugin declares under `schedules/`. */
 export interface PluginScheduleSurface {
   /** Schedule name: the declaration directory's name. */
@@ -124,15 +126,14 @@ function listSkillIds(skillsDir: string): string[] {
 /** Matches a `---` delimited YAML frontmatter block at the start of a file. */
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 
+const ScheduleConfigSchema = z.object({
+  expression: z.string().refine((expression) => expression.trim() !== ""),
+});
+
 /** Read the raw `expression` string from a parsed schedule config, or `null`. */
 function readConfigExpression(config: unknown): string | null {
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
-    return null;
-  }
-  const expression = (config as Record<string, unknown>).expression;
-  return typeof expression === "string" && expression.trim() !== ""
-    ? expression
-    : null;
+  const parsed = ScheduleConfigSchema.safeParse(config);
+  return parsed.success ? parsed.data.expression : null;
 }
 
 /**

package/src/cli.ts

@@ -157,7 +157,7 @@ export async function startCli(): Promise<void> {
         }),
       );
 
-      const result = await new Promise<{
+      return await new Promise<{
         ok: boolean;
         error?: string;
         message?: string;
@@ -208,8 +208,6 @@ export async function startCli(): Promise<void> {
           checkResult();
         }
       });
-
-      return result;
     } catch {
       return { ok: false };
     }

package/src/config/__tests__/chat-settings.test.ts

@@ -0,0 +1,121 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { describe, expect, test } from "bun:test";
+
+import { getWorkspaceConfigPath } from "../../util/platform.js";
+import { loadRawConfig, saveRawConfig } from "../loader.js";
+import { AssistantConfigSchema } from "../schema.js";
+import { AutoArchiveConfigSchema } from "../schemas/conversations.js";
+
+describe("chat settings config", () => {
+  test("missing settings preserve existing behavior", () => {
+    const config = AssistantConfigSchema.parse({});
+    expect(config.conversations.autoArchive).toEqual({
+      enabled: false,
+      afterDays: 7,
+    });
+    expect(config.notifications.newMessageEnabled).toBe(true);
+  });
+
+  test.each([1, 7, 14, 30])(
+    "accepts a %i-day inactivity interval",
+    (afterDays) => {
+      expect(AutoArchiveConfigSchema.parse({ afterDays })).toEqual({
+        enabled: false,
+        afterDays,
+      });
+    },
+  );
+
+  test.each([
+    { conversations: { autoArchive: { enabled: "false" } } },
+    { conversations: { autoArchive: { afterDays: 2 } } },
+    { conversations: { autoArchive: { afterDays: 1.5 } } },
+    { conversations: { autoArchive: { enabled: null } } },
+    { conversations: { autoArchive: [] } },
+    { conversations: null },
+    { notifications: { newMessageEnabled: 1 } },
+    { notifications: { newMessageEnabled: null } },
+    { notifications: [] },
+  ])(
+    "raw writes reject invalid settings before changing disk: %j",
+    (invalid) => {
+      const original = {
+        conversations: { autoArchive: { enabled: true, afterDays: 14 } },
+        notifications: { newMessageEnabled: false },
+      };
+      saveRawConfig(original);
+      expect(() => saveRawConfig(invalid)).toThrow();
+      expect(loadRawConfig()).toEqual(original);
+    },
+  );
+
+  test.each([
+    { conversations: false },
+    { conversations: [] },
+    { conversations: null },
+    { conversations: { autoArchive: "legacy" } },
+    { conversations: { autoArchive: [] } },
+    { conversations: { autoArchive: null } },
+    { conversations: { autoArchive: { enabled: "true", afterDays: 2 } } },
+    { conversations: { autoArchive: { enabled: null, afterDays: null } } },
+    { notifications: "legacy" },
+    { notifications: [] },
+    { notifications: null },
+    { notifications: { newMessageEnabled: "false" } },
+    { notifications: { newMessageEnabled: null } },
+  ])("raw unrelated writes preserve untouched legacy values: %j", (legacy) => {
+    const original = { ...legacy, maxStepsPerSession: 75 };
+    writeFileSync(getWorkspaceConfigPath(), JSON.stringify(original));
+
+    const updated = { ...loadRawConfig(), maxStepsPerSession: 100 };
+    saveRawConfig(updated);
+
+    expect(loadRawConfig()).toEqual({ ...original, maxStepsPerSession: 100 });
+  });
+
+  test.each([
+    [{ conversations: false }, { conversations: [] }],
+    [
+      { conversations: [] },
+      { conversations: { autoArchive: { enabled: "true" } } },
+    ],
+    [
+      { conversations: { autoArchive: null } },
+      { conversations: { autoArchive: { afterDays: 2 } } },
+    ],
+    [
+      { notifications: { newMessageEnabled: "false" } },
+      { notifications: { newMessageEnabled: "true" } },
+    ],
+    [
+      { conversations: { autoArchive: { enabled: "true", afterDays: 2 } } },
+      { conversations: { autoArchive: { enabled: "true", afterDays: 3 } } },
+    ],
+  ])("raw writes reject changed invalid values: %j -> %j", (previous, next) => {
+    const configPath = getWorkspaceConfigPath();
+    writeFileSync(configPath, JSON.stringify(previous));
+    const originalBytes = readFileSync(configPath, "utf-8");
+
+    expect(() => saveRawConfig(next)).toThrow();
+
+    expect(readFileSync(configPath, "utf-8")).toBe(originalBytes);
+  });
+
+  test("raw writes can repair one leaf while preserving other legacy values", () => {
+    writeFileSync(
+      getWorkspaceConfigPath(),
+      JSON.stringify({
+        conversations: { autoArchive: { enabled: "true", afterDays: 2 } },
+        notifications: null,
+      }),
+    );
+    const repaired = {
+      conversations: { autoArchive: { enabled: true, afterDays: 2 } },
+      notifications: null,
+    };
+
+    saveRawConfig(repaired);
+
+    expect(loadRawConfig()).toEqual(repaired);
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -16,6 +16,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { z } from "zod";
+
 import { ipcGetFeatureFlags } from "../ipc/gateway-client.js";
 import { getLogger } from "../util/logger.js";
 import {
@@ -47,6 +49,22 @@ export type FeatureFlagDefaultsRegistry = Record<string, FeatureFlagDefault>;
 let cachedDefaults: FeatureFlagDefaultsRegistry | undefined;
 
 const REGISTRY_FILENAME = "feature-flag-registry.json";
+const FeatureFlagRegistryEntrySchema = z
+  .object({
+    scope: z.enum(["assistant", "both"]).optional().catch(undefined),
+    key: z.string().optional().catch(undefined),
+    defaultEnabled: z
+      .union([z.boolean(), z.string()])
+      .optional()
+      .catch(undefined),
+    description: z.string().catch(""),
+    label: z.string().catch(""),
+  })
+  .optional()
+  .catch(undefined);
+const FeatureFlagRegistrySchema = z.object({
+  flags: z.array(FeatureFlagRegistryEntrySchema),
+});
 
 function loadDefaultsRegistry(): FeatureFlagDefaultsRegistry {
   if (cachedDefaults) {
@@ -100,39 +118,26 @@ function loadDefaultsRegistry(): FeatureFlagDefaultsRegistry {
  * filtering to flags the backend consumes (`assistant`- and `both`-scope).
  */
 function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return {};
-  }
-
-  const registry = parsed as { version?: number; flags?: unknown[] };
-  if (!Array.isArray(registry.flags)) {
+  const registry = FeatureFlagRegistrySchema.safeParse(parsed);
+  if (!registry.success) {
     return {};
   }
 
   const result: FeatureFlagDefaultsRegistry = {};
-  for (const flag of registry.flags) {
-    if (!flag || typeof flag !== "object" || Array.isArray(flag)) {
-      continue;
-    }
-    const entry = flag as Record<string, unknown>;
-    if (entry.scope !== "assistant" && entry.scope !== "both") {
-      continue;
-    }
-    if (typeof entry.key !== "string") {
-      continue;
-    }
+  for (const entry of registry.data.flags) {
     if (
-      typeof entry.defaultEnabled !== "boolean" &&
-      typeof entry.defaultEnabled !== "string"
+      !entry ||
+      entry.scope === undefined ||
+      entry.key === undefined ||
+      entry.defaultEnabled === undefined
     ) {
       continue;
     }
 
-    result[entry.key as string] = {
+    result[entry.key] = {
       defaultEnabled: entry.defaultEnabled,
-      description:
-        typeof entry.description === "string" ? entry.description : "",
-      label: typeof entry.label === "string" ? entry.label : "",
+      description: entry.description,
+      label: entry.label,
     };
   }
   return result;

package/src/config/bundled-skills/computer-use/SKILL.md

@@ -37,6 +37,26 @@ The tree is walked to a limited depth to keep steps fast, and says when it was
 cut off. If the element you need is not in it, call `computer_use_observe` with
 `full_tree: true`.
 
+## Coordinates and live editing
+
+Prefer element IDs from the latest observation. Click, scroll and drag
+coordinates are **screen points**, not screenshot pixels. For a desktop
+screenshot, use the per-axis conversion in its observation metadata. If you
+crop or resize the image, map back to the original screenshot first. Observe
+again after the layout changes; an older image is not a current target.
+
+During live editing, use the app's zoom and track-height controls, then inspect
+the fresh screenshot. Avoid installing image libraries or repeatedly cropping
+and measuring screenshot pixels just to locate a UI control or waveform.
+Reserve scripted image or media analysis for tasks that actually require it.
+If an action does not produce the expected visible result, check focus and the
+coordinate mapping before repeating it.
+
+Waveform pixels do not reveal spoken words. If an edit depends on audio you
+cannot hear or a boundary you cannot see, ask for a timestamp, a user-positioned
+playhead, or the source media. Do not guess the cut point or claim an edit
+succeeded without observing its result.
+
 ## Scripting apps (macOS)
 
 Reach for `computer_use_run_applescript` first when an app can be driven by

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -21,7 +21,7 @@
           },
           "full_tree": {
             "type": "boolean",
-            "description": "On connected personal computers, walk the accessibility tree to full depth. The virtual desktop uses a bounded tree; use screenshot coordinates when an element is not listed."
+            "description": "On connected personal computers, walk the accessibility tree to full depth. The virtual desktop uses a bounded tree; use coordinates converted from the screenshot metadata when an element is not listed."
           },
           "target_client_id": {
             "type": "string",
@@ -57,11 +57,11 @@
           },
           "x": {
             "type": "integer",
-            "description": "X coordinate on screen (fallback when no element_id)"
+            "description": "X in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "y": {
             "type": "integer",
-            "description": "Y coordinate on screen (fallback when no element_id)"
+            "description": "Y in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "reasoning": {
             "type": "string",
@@ -170,11 +170,11 @@
           },
           "x": {
             "type": "integer",
-            "description": "X coordinate on screen (fallback when no element_id)"
+            "description": "X in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "y": {
             "type": "integer",
-            "description": "Y coordinate on screen (fallback when no element_id)"
+            "description": "Y in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "direction": {
             "type": "string",
@@ -222,11 +222,11 @@
           },
           "x": {
             "type": "integer",
-            "description": "Source X coordinate (fallback when no element_id)"
+            "description": "Source X in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "y": {
             "type": "integer",
-            "description": "Source Y coordinate (fallback when no element_id)"
+            "description": "Source Y in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
           },
           "to_element_id": {
             "type": "integer",
@@ -234,11 +234,11 @@
           },
           "to_x": {
             "type": "integer",
-            "description": "Destination X coordinate (fallback when no to_element_id)"
+            "description": "Destination X in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no to_element_id)."
           },
           "to_y": {
             "type": "integer",
-            "description": "Destination Y coordinate (fallback when no to_element_id)"
+            "description": "Destination Y in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no to_element_id)."
           },
           "reasoning": {
             "type": "string",
@@ -408,11 +408,11 @@
                 },
                 "x": {
                   "type": "integer",
-                  "description": "click, double_click, right_click, scroll: X coordinate on screen (fallback when no element_id)"
+                  "description": "click, double_click, right_click, scroll: X in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
                 },
                 "y": {
                   "type": "integer",
-                  "description": "click, double_click, right_click, scroll: Y coordinate on screen (fallback when no element_id)"
+                  "description": "click, double_click, right_click, scroll: Y in screen points, not screenshot pixels. Apply the latest observation's coordinate mapping (fallback when no element_id)."
                 },
                 "direction": {
                   "type": "string",