@rudderjs/ai 1.5.0 → 1.6.1

package/dist/commands/ai-eval.js

@@ -0,0 +1,378 @@
+/**
+ * `pnpm rudder ai:eval` — discover `evals/**\/*.eval.ts` suites,
+ * run each, and report. Console reporter by default; `--json` emits
+ * a machine-readable envelope to stdout for CI.
+ *
+ * Registered from the CLI loader (`packages/cli/src/index.ts`)
+ * — the AiProvider doesn't own this so it surfaces even when the
+ * user app fails to boot, matching the `command:list --json`
+ * graceful-degradation pattern from #349.
+ */
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runSuite, reportConsole, evalSuite, stepsFromResponse } from '../eval/index.js';
+import { reportJson } from '../eval/json-reporter.js';
+import { reportHtml } from '../eval/html-reporter.js';
+import { defaultFixturesDir, readFixture, writeFixture } from '../eval/fixtures.js';
+import { AiFake } from '../fake.js';
+/** Register the `ai:eval` command on the rudder runner. */
+export function registerAiEvalCommand(rudder) {
+    rudder.command('ai:eval', async (rawArgs) => {
+        const code = await runEvalCli(parseArgs(rawArgs));
+        if (code !== 0)
+            process.exit(code);
+    }).description('Run eval suites — pnpm rudder ai:eval [name-pattern] [--bail] [--json] [--record|--replay] [--html <path>]');
+}
+// ─── Args parser ─────────────────────────────────────────
+const VALUE_FLAGS = new Set(['--html']);
+/**
+ * Parse the rest-of-line. Recognizes:
+ *  - boolean flags: `--bail`, `--json`, `--record`, `--replay`
+ *  - value flags  : `--html <path>` or `--html=<path>`
+ *  - one positional name filter (anything not consumed above)
+ */
+export function parseArgs(args) {
+    const positional = [];
+    const opts = { bail: false, json: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--')) {
+            positional.push(a);
+            continue;
+        }
+        // `--flag=value` form
+        const eq = a.indexOf('=');
+        const name = eq >= 0 ? a.slice(0, eq) : a;
+        const inline = eq >= 0 ? a.slice(eq + 1) : undefined;
+        if (name === '--bail') {
+            opts.bail = true;
+            continue;
+        }
+        if (name === '--json') {
+            opts.json = true;
+            continue;
+        }
+        if (name === '--record') {
+            opts.record = true;
+            continue;
+        }
+        if (name === '--replay') {
+            opts.replay = true;
+            continue;
+        }
+        if (VALUE_FLAGS.has(name)) {
+            const value = inline ?? args[i + 1];
+            if (!inline)
+                i++; // consumed the next arg
+            if (!value)
+                throw new Error(`[RudderJS AI] ${name} requires a value`);
+            if (name === '--html')
+                opts.html = value;
+            continue;
+        }
+        // unknown flag — surface as positional so the user sees the typo
+        positional.push(a);
+    }
+    if (positional[0])
+        opts.filter = positional[0];
+    return opts;
+}
+// ─── Runner ──────────────────────────────────────────────
+/**
+ * Execute the CLI flow. Returns the process exit code (0 = all pass,
+ * 1 = at least one suite had a failure or no suites discovered).
+ *
+ * The handler is `process.exit`-free so tests can drive it directly.
+ */
+export async function runEvalCli(opts, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    if (opts.record && opts.replay) {
+        stderr.write('[ai:eval] --record and --replay are mutually exclusive\n');
+        return 1;
+    }
+    const pattern = await Promise.resolve((deps.configPattern ?? loadConfigPattern)()) ?? 'evals/**/*.eval.ts';
+    const discover = deps.discover ?? discoverSuiteFiles;
+    const files = await discover(cwd, pattern);
+    if (files.length === 0) {
+        stderr.write(`[ai:eval] no suites found matching ${pattern}\n`);
+        return opts.json ? emitJson(stdout, []) : 1;
+    }
+    const loader = deps.loadSuite ?? defaultSuiteLoader;
+    const fixturesDir = deps.fixturesDir ?? defaultFixturesDir(cwd);
+    const reports = [];
+    const fullReports = [];
+    let exitCode = 0;
+    // `--replay` swaps the global runtime once, restored when we're done.
+    // The per-case fixture is set on the AiFake instance inside the
+    // wrapped agent factory just before each case's `agent.prompt()`.
+    let fake = null;
+    if (opts.replay)
+        fake = AiFake.fake();
+    try {
+        for (const file of files) {
+            let suite;
+            try {
+                suite = await loader(file);
+            }
+            catch (err) {
+                stderr.write(`[ai:eval] failed to load ${path.relative(cwd, file)}: ${formatError(err)}\n`);
+                exitCode = 1;
+                if (opts.bail)
+                    break;
+                continue;
+            }
+            if (!suite) {
+                stderr.write(`[ai:eval] ${path.relative(cwd, file)} has no default eval suite — skipping\n`);
+                continue;
+            }
+            if (opts.filter && !suite.name.toLowerCase().includes(opts.filter.toLowerCase()))
+                continue;
+            const decorated = await decorateForMode(suite, opts, { fixturesDir, stderr, fake });
+            const report = await runSuite(decorated);
+            fullReports.push(report);
+            if (opts.json) {
+                reports.push(reportJson(report));
+            }
+            else {
+                reportConsole(report, { log: (s) => stdout.write(`${s}\n`) });
+            }
+            if (report.failed > 0) {
+                exitCode = 1;
+                if (opts.bail)
+                    break;
+            }
+        }
+    }
+    finally {
+        if (fake)
+            fake.restore();
+    }
+    if (opts.json)
+        emitJson(stdout, reports);
+    if (opts.html)
+        await writeHtmlReport(opts.html, fullReports, cwd, stderr);
+    return exitCode;
+}
+async function writeHtmlReport(htmlPath, reports, cwd, stderr) {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    const abs = path.isAbsolute(htmlPath) ? htmlPath : path.resolve(cwd, htmlPath);
+    try {
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, reportHtml(reports));
+        stderr.write(`[ai:eval] wrote HTML report → ${path.relative(cwd, abs)}\n`);
+    }
+    catch (err) {
+        stderr.write(`[ai:eval] failed to write HTML report ${abs}: ${formatError(err)}\n`);
+    }
+}
+function emitJson(stdout, suites) {
+    stdout.write(`${JSON.stringify({ suites }, null, 2)}\n`);
+    return 0;
+}
+function formatError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Wrap a suite so each case captures the response (`--record`) or
+ * pre-loads the fake's sequence (`--replay`) before running. A
+ * normal run returns the suite untouched.
+ *
+ * Implemented as a per-case `agent` / `assert` decoration so the
+ * runner stays unchanged — `runSuite` doesn't need to know about
+ * the fixture format. The original `agent`/`assert` for each case
+ * are still called; we just slip work in around them.
+ *
+ * For replay, fixtures load up-front (sync factory contract) so the
+ * AiFake is primed before each `agent.prompt()` runs.
+ */
+async function decorateForMode(suite, opts, ctx) {
+    if (!opts.record && !opts.replay)
+        return suite;
+    // Pre-load every fixture for replay so the per-case factory can
+    // call `respondWithSequence` synchronously.
+    const replaySteps = new Map();
+    if (opts.replay) {
+        for (let i = 0; i < suite.spec.cases.length; i++) {
+            const c = suite.spec.cases[i];
+            const caseName = c.name ?? `case-${i}`;
+            try {
+                const fixture = await readFixture(ctx.fixturesDir, suite.name, caseName);
+                if (fixture)
+                    replaySteps.set(caseName, fixture.steps);
+                else
+                    ctx.stderr.write(`[ai:eval] no fixture for ${suite.name}/${caseName} — running against live provider\n`);
+            }
+            catch (err) {
+                ctx.stderr.write(`[ai:eval] fixture load error for ${suite.name}/${caseName}: ${formatError(err)}\n`);
+            }
+        }
+    }
+    const wrapped = suite.spec.cases.map((c, i) => {
+        const caseName = c.name ?? `case-${i}`;
+        const baseFactory = c.agent ?? suite.spec.agent;
+        const baseAssert = c.assert;
+        const factory = opts.replay
+            ? wrapReplayFactory(baseFactory, replaySteps.get(caseName), ctx.fake)
+            : baseFactory;
+        const assert = opts.record
+            ? wrapRecordAssert(baseAssert, suite.name, caseName, c.input, ctx)
+            : baseAssert;
+        const out = {
+            input: c.input,
+            assert,
+            agent: factory,
+        };
+        if (c.name)
+            out.name = c.name;
+        if (c.timeout !== undefined)
+            out.timeout = c.timeout;
+        if (c.skip !== undefined)
+            out.skip = c.skip;
+        return out;
+    });
+    const newSpec = {
+        agent: suite.spec.agent,
+        cases: wrapped,
+    };
+    if (suite.spec.timeout !== undefined)
+        newSpec.timeout = suite.spec.timeout;
+    return evalSuite(suite.name, newSpec);
+}
+/**
+ * Replay path: before each case runs, prime the shared `AiFake`
+ * with the case's recorded steps. When the fixture is missing the
+ * factory still returns the agent — it'll hit whatever the AiFake
+ * is currently scripted to return (typically falling back to the
+ * default ambient response, which surfaces as an obvious diff in
+ * the case's assertion).
+ */
+function wrapReplayFactory(base, steps, fake) {
+    return () => {
+        if (fake && steps)
+            fake.respondWithSequence(steps);
+        return base();
+    };
+}
+/**
+ * Record path: after each case's assertion runs, capture the
+ * agent response's assistant turns to the fixture file. Wrapping
+ * the assert is the cleanest hook — the runner already passes
+ * `response` into it, and the wrapped fn still returns the
+ * original assertion's result.
+ */
+function wrapRecordAssert(base, suite, caseName, input, ctx) {
+    return async (response, mctx) => {
+        try {
+            const file = await writeFixture(ctx.fixturesDir, suite, caseName, {
+                input,
+                steps: stepsFromResponse(response),
+            });
+            ctx.stderr.write(`[ai:eval] recorded ${path.relative(process.cwd(), file)}\n`);
+        }
+        catch (err) {
+            ctx.stderr.write(`[ai:eval] failed to record ${suite}/${caseName}: ${formatError(err)}\n`);
+        }
+        return base(response, mctx);
+    };
+}
+// ─── File discovery ──────────────────────────────────────
+/**
+ * Recursive walk constrained to a `<dir>/**\/*<suffix>` shape.
+ * Returns absolute paths sorted lexicographically for stable test
+ * output and predictable `--bail` ordering.
+ */
+export async function discoverSuiteFiles(cwd, pattern) {
+    const { root, suffix } = parsePattern(pattern);
+    const absRoot = path.resolve(cwd, root);
+    const out = [];
+    await walk(absRoot, suffix, out);
+    return out.sort();
+}
+/**
+ * Tiny pattern parser — supports `<dir>/**\/*<suffix>` and bare
+ * `*<suffix>` (current directory). Anything more elaborate is
+ * deferred to userland (run a custom script that imports `runSuite`).
+ *
+ * Examples:
+ *   `evals/**\/*.eval.ts`     → root=`evals`,    suffix=`.eval.ts`
+ *   `tests/agents/**\/*.ts`   → root=`tests/agents`, suffix=`.ts`
+ *   `*.eval.ts`               → root=`.`,        suffix=`.eval.ts`
+ */
+function parsePattern(pattern) {
+    const doubleStar = pattern.indexOf('**');
+    let prefix;
+    let postfix;
+    if (doubleStar >= 0) {
+        prefix = pattern.slice(0, doubleStar).replace(/\/$/, '');
+        postfix = pattern.slice(doubleStar + 2).replace(/^\//, '');
+    }
+    else {
+        const lastSlash = pattern.lastIndexOf('/');
+        prefix = lastSlash >= 0 ? pattern.slice(0, lastSlash) : '';
+        postfix = lastSlash >= 0 ? pattern.slice(lastSlash + 1) : pattern;
+    }
+    if (!postfix.startsWith('*')) {
+        throw new Error(`[RudderJS AI] Unsupported eval pattern "${pattern}". ` +
+            `Expected <dir>/**/*<suffix> or *<suffix>.`);
+    }
+    return {
+        root: prefix || '.',
+        suffix: postfix.slice(1),
+    };
+}
+async function walk(dir, suffix, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                continue;
+            await walk(p, suffix, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith(suffix)) {
+            out.push(p);
+        }
+    }
+}
+// ─── Suite loader ────────────────────────────────────────
+async function defaultSuiteLoader(file) {
+    const mod = await import(pathToFileURL(file).href);
+    const candidate = (mod['default'] ?? mod['suite']);
+    if (!candidate || typeof candidate.name !== 'string' || !candidate.spec)
+        return null;
+    return candidate;
+}
+// ─── Config lookup ───────────────────────────────────────
+/**
+ * Read `config('ai').eval.pattern` from the booted app. Returns
+ * `null` (default pattern) when `@rudderjs/core` isn't loadable
+ * or the app didn't boot — the CLI must still work in
+ * introspective mode (#349).
+ */
+async function loadConfigPattern() {
+    try {
+        // Dynamic import so the static graph doesn't pin `@rudderjs/core`
+        // (optional peer). Falls back to default when core isn't loadable
+        // or the app didn't boot.
+        const core = await import('@rudderjs/core');
+        if (typeof core.config !== 'function')
+            return null;
+        const cfg = core.config('ai');
+        return cfg?.eval?.pattern ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=ai-eval.js.map

package/dist/commands/ai-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-eval.js","sourceRoot":"","sources":["../../src/commands/ai-eval.ts"],"names":[],"mappings":"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"}

package/dist/computer-use/actions.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Action vocabulary for `@rudderjs/ai/computer-use` (#A7 Phase 1).
+ *
+ * Mirrors Anthropic's `computer_20250124` tool schema verbatim — see
+ * https://docs.anthropic.com/en/docs/build-with-claude/tool-use/computer-use-tool
+ *
+ * The model emits a {@link ComputerAction} as the JSON argument of a
+ * `computer` tool call; the executor (see `./playwright.ts`) dispatches
+ * the action against a Playwright `Page` and returns a
+ * {@link ComputerActionResult} the agent loop forwards back to the model.
+ *
+ * # Why mirror Anthropic exactly?
+ *
+ * Computer-use is `Anthropic-only` in v1 (see plan
+ * `docs/plans/2026-05-10-ai-computer-use.md`). Claude is fine-tuned on
+ * this exact action vocabulary; reusing the schema means:
+ *
+ * - Phase 2's `computerUseTool({ page })` factory maps cleanly to
+ *   Anthropic's native `{ type: 'computer_20250124', name: 'computer',
+ *   display_width_px, display_height_px }` block — zero translation
+ *   layer.
+ * - When OpenAI or Google's native computer-use APIs mature enough to
+ *   route through, only the provider adapter changes; the schema and
+ *   executor stay put.
+ *
+ * # Coordinates
+ *
+ * `[x, y]` in viewport pixels. Origin is top-left. Anthropic suggests a
+ * 1280×800 viewport for Claude's training distribution; the executor
+ * does not validate bounds — out-of-viewport coordinates pass through
+ * to Playwright (which clips the cursor to viewport edges).
+ *
+ * # Modifier text on click / scroll actions
+ *
+ * Anthropic encodes "hold these modifier keys while clicking" as a `+`
+ * separated string on the `text` field — e.g.
+ * `{ action: 'left_click', coordinate: [400, 200], text: 'shift+ctrl' }`.
+ * The executor translates `cmd`/`super`/`meta` → `Meta`,
+ * `ctrl`/`control` → `Control`, etc. before passing to Playwright.
+ */
+/** Viewport pixel coordinate, top-left origin. `[x, y]`. */
+export type Coordinate = readonly [number, number];
+/**
+ * Discriminated union of every action Anthropic's `computer_20250124`
+ * tool can emit. The executor dispatches on `action`; downstream code
+ * should treat unknown variants as a forward-compatibility hazard
+ * rather than a bug — Anthropic versions the schema with dated suffixes
+ * (e.g. a future `computer_20260101` may add new variants we'll route
+ * here once supported).
+ */
+export type ComputerAction = {
+    action: 'screenshot';
+} | {
+    action: 'cursor_position';
+}
+/** Pause for `duration` seconds. Useful between an action that triggers async UI and the screenshot that should observe the result. */
+ | {
+    action: 'wait';
+    duration: number;
+} | {
+    action: 'mouse_move';
+    coordinate: Coordinate;
+}
+/** Single left-button click. `text` holds optional modifier keys, `+`-separated (e.g. `'shift+ctrl'`). */
+ | {
+    action: 'left_click';
+    coordinate: Coordinate;
+    text?: string;
+} | {
+    action: 'right_click';
+    coordinate: Coordinate;
+    text?: string;
+} | {
+    action: 'middle_click';
+    coordinate: Coordinate;
+    text?: string;
+} | {
+    action: 'double_click';
+    coordinate: Coordinate;
+    text?: string;
+} | {
+    action: 'triple_click';
+    coordinate: Coordinate;
+    text?: string;
+}
+/** Press the left mouse button. Pair with `left_mouse_up` to drag. `coordinate` (optional) moves first. */
+ | {
+    action: 'left_mouse_down';
+    coordinate?: Coordinate;
+}
+/** Release the left mouse button. `coordinate` (optional) moves first. */
+ | {
+    action: 'left_mouse_up';
+    coordinate?: Coordinate;
+}
+/** Type literal text. No modifier handling — use `key` for shortcuts. */
+ | {
+    action: 'type';
+    text: string;
+}
+/** Press a key chord. `text` is `+`-separated (e.g. `'ctrl+a'`, `'Return'`, `'cmd+shift+t'`). */
+ | {
+    action: 'key';
+    text: string;
+}
+/** Hold a single key for `duration` seconds. `text` is one key, not a chord. */
+ | {
+    action: 'hold_key';
+    text: string;
+    duration: number;
+}
+/** Scroll at `coordinate`. `scroll_amount` is in mouse-wheel "clicks" (~100px each). `text` holds optional modifiers. */
+ | {
+    action: 'scroll';
+    coordinate: Coordinate;
+    scroll_direction: 'up' | 'down' | 'left' | 'right';
+    scroll_amount: number;
+    text?: string;
+};
+/**
+ * Tool-result content the agent loop hands back to the model after each
+ * action. Shape matches Anthropic's tool-result block content vocabulary:
+ *
+ * - `image` carries a PNG screenshot. The agent loop wraps this as
+ *   `{ type: 'image', source: { type: 'base64', media_type, data } }`
+ *   when serializing to the API.
+ * - `text` carries a one-line confirmation (`"left-clicked at (400, 200)"`)
+ *   or the response of an introspective action (`cursor_position`).
+ * - `error` carries the failure text from a Playwright throw. Caller
+ *   typically maps this onto `{ is_error: true, content: [...] }` in
+ *   the tool-result block so the model knows the action failed and can
+ *   retry / recover.
+ */
+export type ComputerActionResult = {
+    type: 'image';
+    media_type: 'image/png';
+    data: Uint8Array;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'error';
+    text: string;
+};
+/**
+ * Per-run state the executor mutates. Tracks the last known cursor
+ * position so the `cursor_position` action can answer it (Playwright
+ * has no native API to read the synthesized mouse position).
+ *
+ * Create one with {@link makeExecutorState} per agent run; pass the
+ * same instance to every {@link executeComputerAction} call.
+ */
+export interface ComputerExecutorState {
+    /** Last known cursor position in viewport pixels. Updated on move/click/drag. */
+    cursor: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Construct a fresh {@link ComputerExecutorState}. Optional `initial`
+ * seeds the cursor (defaults to `(0, 0)`).
+ */
+export declare function makeExecutorState(initial?: {
+    x: number;
+    y: number;
+}): ComputerExecutorState;
+/**
+ * Structural subset of Playwright's `Page` the executor calls. Defining
+ * this here means {@link executeComputerAction} types correctly without
+ * `@rudderjs/ai` taking a hard dependency on the `playwright` package
+ * (which carries a 300MB+ Chromium download). Apps install Playwright
+ * themselves and pass `page` in.
+ *
+ * Any object with this shape works — real Playwright `Page`,
+ * `puppeteer-core`'s `Page` (close enough), or a hand-rolled mock for
+ * tests. Phase 2's `computerUseTool({ page })` accepts the same type.
+ */
+export interface PageLike {
+    mouse: PageMouseLike;
+    keyboard: PageKeyboardLike;
+    /** Take a screenshot of the current viewport. Returns PNG bytes by default. */
+    screenshot(options?: {
+        type?: 'png' | 'jpeg';
+    }): Promise<Uint8Array>;
+}
+export interface PageMouseLike {
+    move(x: number, y: number, options?: {
+        steps?: number;
+    }): Promise<void>;
+    click(x: number, y: number, options?: {
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    }): Promise<void>;
+    down(options?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    up(options?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+}
+export interface PageKeyboardLike {
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    press(key: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    down(key: string): Promise<void>;
+    up(key: string): Promise<void>;
+}
+//# sourceMappingURL=actions.d.ts.map

package/dist/computer-use/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/computer-use/actions.ts"],"names":[],"mappings":"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"}

package/dist/computer-use/actions.js

@@ -0,0 +1,48 @@
+/**
+ * Action vocabulary for `@rudderjs/ai/computer-use` (#A7 Phase 1).
+ *
+ * Mirrors Anthropic's `computer_20250124` tool schema verbatim — see
+ * https://docs.anthropic.com/en/docs/build-with-claude/tool-use/computer-use-tool
+ *
+ * The model emits a {@link ComputerAction} as the JSON argument of a
+ * `computer` tool call; the executor (see `./playwright.ts`) dispatches
+ * the action against a Playwright `Page` and returns a
+ * {@link ComputerActionResult} the agent loop forwards back to the model.
+ *
+ * # Why mirror Anthropic exactly?
+ *
+ * Computer-use is `Anthropic-only` in v1 (see plan
+ * `docs/plans/2026-05-10-ai-computer-use.md`). Claude is fine-tuned on
+ * this exact action vocabulary; reusing the schema means:
+ *
+ * - Phase 2's `computerUseTool({ page })` factory maps cleanly to
+ *   Anthropic's native `{ type: 'computer_20250124', name: 'computer',
+ *   display_width_px, display_height_px }` block — zero translation
+ *   layer.
+ * - When OpenAI or Google's native computer-use APIs mature enough to
+ *   route through, only the provider adapter changes; the schema and
+ *   executor stay put.
+ *
+ * # Coordinates
+ *
+ * `[x, y]` in viewport pixels. Origin is top-left. Anthropic suggests a
+ * 1280×800 viewport for Claude's training distribution; the executor
+ * does not validate bounds — out-of-viewport coordinates pass through
+ * to Playwright (which clips the cursor to viewport edges).
+ *
+ * # Modifier text on click / scroll actions
+ *
+ * Anthropic encodes "hold these modifier keys while clicking" as a `+`
+ * separated string on the `text` field — e.g.
+ * `{ action: 'left_click', coordinate: [400, 200], text: 'shift+ctrl' }`.
+ * The executor translates `cmd`/`super`/`meta` → `Meta`,
+ * `ctrl`/`control` → `Control`, etc. before passing to Playwright.
+ */
+/**
+ * Construct a fresh {@link ComputerExecutorState}. Optional `initial`
+ * seeds the cursor (defaults to `(0, 0)`).
+ */
+export function makeExecutorState(initial) {
+    return { cursor: { x: initial?.x ?? 0, y: initial?.y ?? 0 } };
+}
+//# sourceMappingURL=actions.js.map

package/dist/computer-use/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/computer-use/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAqFH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAkC;IAClE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;AAC/D,CAAC"}