Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
#!/usr/bin/env npx tsx
/**
* Cua Driver reference generator.
*
* Builds `cua-driver` (release), runs `cua-driver dump-docs --type all` and
* writes, through the shared renderers in lib/:
*
* - docs/content/docs/cua-driver/reference/index.mdx (the Reference index)
* - docs/content/docs/cua-driver/reference/cli/ (one page per command group)
* - docs/content/docs/cua-driver/reference/mcp-tools/ (an index and a few
* pages of tool categories, MCP_PAGES; every platform on one page: tabs
* where macOS, Linux and Windows differ)
* - scripts/docs-generators/cli-specs/cua-driver.json (the CLI, host
* independent: the CLI-shape lane's oracle)
* - scripts/docs-generators/cli-specs/cua-driver-mcp-<platform>.json (the
* tool registry of each platform)
*
* The tool registry differs per OS and only a native build can dump it, so
* each host owns its own snapshot: a run refreshes (or, with --check,
* verifies) the snapshot of the host it runs on and renders every page from
* the three committed snapshots. The pages are therefore identical on every
* host, and CI on macOS, Linux and Windows each checks its own registry.
* A run verifies only its own host's registry: the other two snapshots are
* rendered as committed. A snapshot that was not dumped natively carries a
* `provenance` note, which every run prints.
*
* Usage:
* pnpm --dir docs docs:generate:cua-driver
* pnpm --dir docs docs:check:cua-driver # drift check (CI)
*
* CUA_DRIVER_BINARY=<path> skips the build and uses that binary.
*/
import { execFileSync } from 'child_process';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import {
type CLIDocumentation,
type CliGroup,
type CliReference,
cliIndexRows,
renderCliReference,
renderReferenceIndex,
} from './lib/cli-mdx';
import { readHeader } from './lib/headers';
import {
type JsonSchema,
type McpCategory,
type McpPage,
type McpReference,
type McpToolEntry,
mcpIndexRows,
renderMcpReference,
} from './lib/mcp-mdx';
import { DOCS_CONTENT, REPO_ROOT, finish, isCheckMode, metaJson, stableJson, syncFiles } from './lib/mdx';
export type { CLIDocumentation };
const CUA_DRIVER_DIR = path.join(REPO_ROOT, 'libs', 'cua-driver', 'rust');
const OUT_DIR = path.join(DOCS_CONTENT, 'cua-driver', 'reference');
const SPEC_DIR = path.join(__dirname, 'cli-specs');
export const DRIVER_CLI_SPEC = path.join(SPEC_DIR, 'cua-driver.json');
const REGENERATE = 'pnpm --dir docs docs:generate:cua-driver';
const TAG_PREFIX = 'cua-driver-rs-v';
// ---------------------------------------------------------------- types
export interface MCPToolDoc {
name: string;
description: string;
input_schema: JsonSchema;
read_only?: boolean;
destructive?: boolean;
idempotent?: boolean;
}
export interface MCPDocumentation {
version?: string;
tools: MCPToolDoc[];
}
export interface DumpDocsOutput {
cli: CLIDocumentation;
mcp: MCPDocumentation;
}
/** A platform's committed registry snapshot. */
export interface McpSnapshot {
/**
* Set only when the snapshot was not dumped by a native build: says where it
* came from. A native run on that host (the generator locally, or the
* ci-check-docs.yml artifact) rewrites the file without it.
*/
provenance?: string;
tools: MCPToolDoc[];
}
/** `tool.param` for every top-level input parameter without a description. */
export function undocumentedParameters(snapshot: McpSnapshot): string[] {
return snapshot.tools.flatMap((tool) =>
Object.entries(tool.input_schema?.properties ?? {})
.filter(([, schema]) => typeof schema?.description !== 'string' || !schema.description.trim())
.map(([param]) => `${tool.name}.${param}`)
);
}
export interface ReferencePlatform {
/** `process.platform` of the host that owns the snapshot. */
host: string;
/** Snapshot key: `cli-specs/cua-driver-mcp-<key>.json`. */
key: string;
/** Display name (tab label). */
name: string;
}
export const referencePlatforms: ReferencePlatform[] = [
{ host: 'darwin', key: 'macos', name: 'macOS' },
{ host: 'linux', key: 'linux', name: 'Linux' },
{ host: 'win32', key: 'windows', name: 'Windows' },
];
export function referencePlatform(host: string): ReferencePlatform {
const platform = referencePlatforms.find((candidate) => candidate.host === host);
if (!platform) throw new Error(`Native MCP reference generation is not implemented for ${host}`);
return platform;
}
export function snapshotPath(platform: ReferencePlatform, dir = SPEC_DIR): string {
return path.join(dir, `cua-driver-mcp-${platform.key}.json`);
}
// ---------------------------------------------------------------- version
export type GitRunner = (command: string, args: readonly string[]) => string;
/**
* Select the highest stable semantic version from Cua Driver release tags.
* Nightlies use their own `nightly-cua-driver-rs-v` prefix and must not affect
* the version recorded in stable reference docs.
*/
export function selectLatestReleasedVersion(tags: readonly string[]): string | undefined {
const versions = tags.flatMap((tag) => {
const match = tag.match(/^cua-driver-rs-v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
if (!match) return [];
return [
{
version: tag.slice(TAG_PREFIX.length),
parts: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])] as const,
},
];
});
versions.sort((a, b) => {
for (let index = 0; index < a.parts.length; index += 1) {
if (a.parts[index] < b.parts[index]) return -1;
if (a.parts[index] > b.parts[index]) return 1;
}
return 0;
});
return versions.at(-1)?.version;
}
function runGit(command: string, args: readonly string[]): string {
return execFileSync(command, [...args], { encoding: 'utf-8', cwd: REPO_ROOT });
}
/** Get the latest stable released version from git tags. */
export function getLatestReleasedVersion(git: GitRunner = runGit): string {
let output: string;
try {
output = git('git', ['tag', '--list', `${TAG_PREFIX}*`]);
} catch (error) {
const detail = error instanceof Error ? `: ${error.message}` : '';
throw new Error(`Failed to list Cua Driver release tags with git${detail}`);
}
const version = selectLatestReleasedVersion(output.split(/\r?\n/).filter(Boolean));
if (!version) {
throw new Error(
`No stable Cua Driver release tag matching ${TAG_PREFIX}<major>.<minor>.<patch> was found`
);
}
return version;
}
// ---------------------------------------------------------------- CLI
export const CLI_GROUPS: CliGroup[] = [
{
slug: 'serve-and-configure',
title: 'Serve, configure and update',
summary:
'Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel',
commands: [
'mcp', 'mcp-config', 'list-tools', 'describe', 'call', 'manifest', 'dump-docs',
'serve', 'stop', 'status', 'sessions', 'revoke', 'autostart',
'permissions', 'doctor', 'diagnose', 'test',
'config', 'telemetry', 'cursor-theme', 'cursor',
'check-update', 'update', 'channel',
],
},
{
slug: 'skills-recording-and-history',
title: 'Skills, recording and history',
summary: 'The agent skill pack, signed extensions and the perception parser; trajectory recording; the Computer History preview',
commands: ['skills', 'extension', 'perception', 'recording', 'history'],
},
];
export function cliReference(cli: CLIDocumentation): CliReference {
return { product: 'cua-driver', cli, groups: CLI_GROUPS, generator: REGENERATE, source: 'cua-driver dump-docs --type cli' };
}
// ---------------------------------------------------------------- MCP
export const MCP_CATEGORIES: Array<McpCategory & { tools: string[] }> = [
{
slug: 'apps-and-windows',
title: 'App and window tools',
summary: 'List, launch, quit, front and arrange apps and windows',
tools: ['list_apps', 'list_windows', 'launch_app', 'kill_app', 'bring_to_front', 'set_window_frame', 'invoke_menu', 'debug_window_info'],
},
{
slug: 'window-state',
title: 'Window state tools',
summary: 'Screenshots, accessibility trees, verification and visual regions of a window',
tools: ['get_window_state', 'get_accessibility_tree', 'verify_state', 'parse_visual_regions'],
},
{
slug: 'screen',
title: 'Screen tools',
summary: 'The desktop, screen size, cursor position and zoomed crops',
tools: ['get_desktop_state', 'get_screen_size', 'get_cursor_position', 'zoom'],
},
{
slug: 'click',
title: 'Click tool',
summary: 'Click by element or pixel',
tools: ['click'],
},
{
slug: 'double-and-right-click',
title: 'Double-click and right-click tools',
summary: 'Double-click and right-click by element or pixel',
tools: ['double_click', 'right_click'],
},
{
slug: 'pointer',
title: 'Pointer tools',
summary: 'Drag, scroll, move the pointer, and press or release buttons',
tools: ['drag', 'scroll', 'move_cursor', 'mouse_button_down', 'mouse_button_up', 'mouse_drag', 'parallel_mouse_drag'],
},
{
slug: 'keyboard',
title: 'Typing tools',
summary: 'Type text into a field or window',
tools: ['type_text', 'type_text_chars'],
},
{
slug: 'keys-and-shortcuts',
title: 'Key and shortcut tools',
summary: 'Press keys and keyboard shortcuts',
tools: ['press_key', 'hotkey'],
},
{
slug: 'values-and-clipboard',
title: 'Value and clipboard tools',
summary: 'Set element values and read or write the clipboard',
tools: ['set_value', 'clipboard_read', 'clipboard_write'],
},
{
slug: 'batch',
title: 'Batch and script tools',
summary: 'Run several action tools, or a script that drives them, in one call',
intro: [
'Use `run_steps` for a fixed list of actions you have already decided. Use `run_script` when the flow needs',
'logic between actions (a loop over rows, a branch on what the app shows, a retry): it runs a JavaScript',
'program over the driver\'s own tools in one call and returns only its result. Every driver call either',
'tool makes passes the same session, permission and approval checks as a direct call.',
'',
'`run_script` runs in a QuickJS sandbox with no filesystem, network, process, timers or environment.',
'Limits: `timeout_ms` (default 30 s, max 120 s), `max_calls` (default 100, max 500), a 32 MiB heap and',
'a 64 KiB script. It is on by default. Whoever runs the driver turns it off with',
'`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json`',
'(`CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work); `set_config` cannot',
'change it.',
].join('\n'),
tools: ['run_steps', 'run_script'],
},
{
slug: 'page',
title: 'Page tools',
summary: 'Read and act on web pages, and prepare and navigate browsers',
tools: ['page', 'get_browser_state', 'browser_prepare', 'browser_navigate'],
},
{
slug: 'browser-input',
title: 'Browser input tools',
summary: 'Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads',
tools: ['browser_click', 'browser_type', 'browser_select', 'browser_pointer', 'browser_dialog', 'browser_set_input_files', 'browser_download'],
},
{
slug: 'sessions',
title: 'Session tools',
summary: 'Start, escalate, inspect and end lifecycle sessions',
tools: ['start_session', 'escalate_session', 'get_session', 'list_sessions', 'get_session_state', 'end_session'],
},
{
slug: 'agent-cursor',
title: 'Agent cursor tools',
summary: 'Show, animate and style the agent cursor',
tools: ['set_agent_cursor_enabled', 'set_agent_cursor_motion', 'set_agent_cursor_theme', 'get_agent_cursor_state'],
},
{
slug: 'recording',
title: 'Recording tools',
summary: 'Record and replay trajectories',
tools: ['start_recording', 'stop_recording', 'get_recording_state', 'replay_trajectory', 'install_ffmpeg'],
},
{
slug: 'maintenance',
title: 'Configuration and maintenance tools',
summary: 'Configuration, permissions, health, updates, extensions and on-demand guides',
tools: ['get_config', 'set_config', 'check_permissions', 'health_report', 'check_for_update', 'install_extension', 'get_guide'],
},
];
/** The MCP tool pages: several categories each. */
export const MCP_PAGES: McpPage[] = [
{
slug: 'apps-windows-and-screen',
title: 'Apps, windows and screen',
summary: 'Apps and windows, window state and screenshots, the screen, and lifecycle sessions',
categories: ['apps-and-windows', 'window-state', 'screen', 'sessions'],
},
{
slug: 'click-and-type',
title: 'Click and type',
summary: 'Clicks, typing, keys and shortcuts, element values and the clipboard',
categories: ['click', 'double-and-right-click', 'keyboard', 'keys-and-shortcuts', 'values-and-clipboard'],
},
{
slug: 'pointer-cursor-and-browser',
title: 'Pointer, cursor and browser',
summary: 'Drag, scroll and move the pointer; the agent cursor; web pages and browser input',
categories: ['pointer', 'agent-cursor', 'page', 'browser-input'],
},
{
slug: 'batch-recording-and-settings',
title: 'Batch, recording and settings',
summary: 'Run several actions in one call, record and replay trajectories, and configuration and maintenance',
categories: ['batch', 'recording', 'maintenance'],
},
];
/** The registry fields the pages use (the per-host version is left out: it drifts every release). */
export function mcpSnapshot(mcp: MCPDocumentation): McpSnapshot {
return {
tools: mcp.tools.map((t) => ({
name: t.name,
description: t.description,
input_schema: t.input_schema,
read_only: Boolean(t.read_only),
destructive: Boolean(t.destructive),
idempotent: Boolean(t.idempotent),
})),
};
}
/** One entry per tool across the platforms' registries. */
export function mergeTools(snapshots: Map<ReferencePlatform, McpSnapshot>): McpToolEntry[] {
const categoryOf = new Map<string, string>();
for (const c of MCP_CATEGORIES) for (const t of c.tools) categoryOf.set(t, c.slug);
const names = new Set<string>();
for (const snap of snapshots.values()) for (const t of snap.tools) names.add(t.name);
const uncategorized = [...names].filter((n) => !categoryOf.has(n)).sort();
if (uncategorized.length) {
throw new Error(
`cua-driver MCP tools without a docs category: ${uncategorized.join(', ')}. Add them to MCP_CATEGORIES in scripts/docs-generators/cua-driver.ts.`
);
}
const order = MCP_CATEGORIES.flatMap((c) => c.tools).filter((n) => names.has(n));
return order.map((name) => {
const present = referencePlatforms.flatMap((p) => {
const tool = snapshots.get(p)?.tools.find((t) => t.name === name);
return tool ? [{ platform: p, tool }] : [];
});
const first = present[0].tool;
return {
name,
description: first.description,
category: categoryOf.get(name)!,
input_schema: first.input_schema,
annotations: { read_only: first.read_only, destructive: first.destructive, idempotent: first.idempotent },
platforms: present.map((x) => x.platform.name),
variants: present.map(({ platform, tool }) => ({
platform: platform.name,
description: tool.description,
input_schema: tool.input_schema,
})),
};
});
}
export function mcpReference(snapshots: Map<ReferencePlatform, McpSnapshot>, version: string): McpReference {
return {
product: 'cua-driver',
server: 'cua-driver mcp',
generator: REGENERATE,
source: 'cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)',
version,
description: 'Every tool cua-driver serves over MCP on macOS, Linux and Windows, with its parameters.',
categories: MCP_CATEGORIES,
tools: mergeTools(snapshots),
header: readHeader('cua-driver', 'mcp-tools'),
platforms: referencePlatforms.map((p) => p.name),
pages: MCP_PAGES,
};
}
// ---------------------------------------------------------------- render
/** Every reference file, keyed by path relative to `reference/`. */
export function renderReference(cli: CLIDocumentation, snapshots: Map<ReferencePlatform, McpSnapshot>): Map<string, string> {
const cliRef = cliReference(cli);
const mcp = mcpReference(snapshots, cli.version);
const rel = new Map<string, string>([...renderCliReference(cliRef), ...renderMcpReference(mcp)]);
rel.set(
'index.mdx',
renderReferenceIndex({
productName: 'Cua Driver',
description: 'Every cua-driver command and every MCP tool on macOS, Linux and Windows, generated from the driver.',
generator: REGENERATE,
source: 'cua-driver dump-docs --type all',
version: cli.version,
sections: [
{ title: 'Commands', column: 'Command group', rows: cliIndexRows(cliRef) },
{ title: 'MCP tools', column: 'Tools', rows: mcpIndexRows(mcp) },
],
})
);
rel.set('meta.json', metaJson('Reference', ['index', 'cli', 'mcp-tools']));
return rel;
}
export function loadSnapshots(dir = SPEC_DIR): Map<ReferencePlatform, McpSnapshot> {
const out = new Map<ReferencePlatform, McpSnapshot>();
for (const p of referencePlatforms) {
const file = snapshotPath(p, dir);
if (!fs.existsSync(file)) throw new Error(`missing ${path.relative(REPO_ROOT, file)}: run the generator on ${p.name}`);
out.set(p, JSON.parse(fs.readFileSync(file, 'utf-8')));
}
return out;
}
/**
* All files for a run on `platform`: that platform's snapshot comes from
* `docs` (the native dump), the other two from `specDir`.
*/
export function referenceFiles(
docs: DumpDocsOutput,
platform: ReferencePlatform,
outDir = OUT_DIR,
specDir = SPEC_DIR
): Map<string, string> {
const snapshots = loadSnapshots(specDir);
const own = mcpSnapshot(docs.mcp);
snapshots.set(platform, own);
const files = new Map<string, string>();
for (const [p, content] of renderReference(docs.cli, snapshots)) files.set(path.join(outDir, p), content);
files.set(path.join(specDir, 'cua-driver.json'), stableJson(docs.cli));
files.set(snapshotPath(platform, specDir), stableJson(own));
return files;
}
// ---------------------------------------------------------------- extract
type DocumentationRunner = (
binary: string,
args: string[],
options: { cwd: string; encoding: 'utf-8'; env: NodeJS.ProcessEnv }
) => string;
export function extractDocumentation(
binary: string,
environment: NodeJS.ProcessEnv = process.env,
run: DocumentationRunner = (command, args, options) =>
execFileSync(command, args, { ...options, maxBuffer: 64 * 1024 * 1024 })
): DumpDocsOutput {
// The docs describe the complete registry: drop tool policies (either case).
const policyVariables = new Set(['CUA_DRIVER_POLICY_FILE', 'CUA_DRIVER_MANAGED_POLICY_FILE']);
const env = Object.fromEntries(
Object.entries(environment).filter(([key]) => !policyVariables.has(key.toUpperCase()))
);
return JSON.parse(
run(binary, ['dump-docs', '--type', 'all', '--pretty'], { cwd: CUA_DRIVER_DIR, encoding: 'utf-8', env })
);
}
/** `$CARGO_TARGET_DIR` when set (relative to the crate dir), else `target/`. */
export function targetDir(dir = CUA_DRIVER_DIR): string {
return process.env.CARGO_TARGET_DIR ? path.resolve(dir, process.env.CARGO_TARGET_DIR) : path.join(dir, 'target');
}
export function resolveDriverBinary(): string {
return (
process.env.CUA_DRIVER_BINARY ||
path.join(targetDir(), 'release', process.platform === 'win32' ? 'cua-driver.exe' : 'cua-driver')
);
}
function resolveCargoCommand(): string {
if (process.env.CARGO) return process.env.CARGO;
for (const candidate of ['cargo', path.join(os.homedir() || '', '.cargo', 'bin', 'cargo'), '/opt/homebrew/bin/cargo', '/usr/local/bin/cargo']) {
try {
execFileSync(candidate, ['--version'], { stdio: 'ignore' });
return candidate;
} catch {
// Try the next candidate.
}
}
throw new Error('cargo not found on PATH; install Rust or set CARGO=/path/to/cargo');
}
function main(): void {
const checkOnly = isCheckMode();
const platform = referencePlatform(process.platform);
if (!process.env.CUA_DRIVER_BINARY) {
execFileSync(resolveCargoCommand(), ['build', '-p', 'cua-driver', '--release'], {
cwd: CUA_DRIVER_DIR,
stdio: 'inherit',
});
}
const docs = extractDocumentation(resolveDriverBinary());
if (!docs.cli.version) docs.cli.version = getLatestReleasedVersion();
const owned = [OUT_DIR, path.join(OUT_DIR, 'cli'), path.join(OUT_DIR, 'mcp-tools')];
const others = referencePlatforms.filter((p) => p !== platform);
console.log(
`Cua Driver: ${checkOnly ? 'verifying' : 'refreshing'} the ${platform.name} registry from a native dump; ` +
`the ${others.map((p) => p.name).join(' and ')} snapshots are rendered as committed ` +
`(only a run on that host verifies them).`
);
for (const [p, snapshot] of loadSnapshots()) {
if (p !== platform && snapshot.provenance) {
console.log(`note: ${path.relative(REPO_ROOT, snapshotPath(p))}: ${snapshot.provenance}`);
}
}
finish(
`Cua Driver (${platform.name} registry)`,
syncFiles(referenceFiles(docs, platform), checkOnly, owned),
checkOnly,
`${REGENERATE} (on ${platform.name})`
);
}
if (require.main === module) main();