@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/hosted/availability.test.js

@@ -0,0 +1,180 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { deriveBrowserAvailability, deriveHostedAvailability, } from './availability.js';
+const EXPECTED_LOCAL_TOOLS = [
+    'antigravity/recent-paths',
+    'antigravity/settings-read',
+    'antigravity/state-get',
+    'antigravity/state-keys',
+    'antigravity/workspaces-list',
+    'mercury/reimbursement-plan',
+    'trae-solo/extensions-list',
+    'trae-solo/recent-workspaces',
+    'trae-solo/settings-read',
+    'trae-solo/skill-fs-installed',
+    'trae-solo/skill-fs-list',
+    'trae-solo/skill-fs-show',
+    'trae-solo/state-get',
+    'trae-solo/state-keys',
+    'trae-solo/task-fs-list',
+    'trae-solo/task-fs-show',
+    'trae-solo/task-fs-turns',
+    'trae-solo/user-rules',
+    'trae-solo/workspaces-list',
+];
+const EXPECTED_DESKTOP_APPS = [
+    'antigravity/add-context',
+    'antigravity/cookies',
+    'antigravity/copy-code',
+    'antigravity/copy-message',
+    'antigravity/delete',
+    'antigravity/display-options',
+    'antigravity/dump',
+    'antigravity/extract-code',
+    'antigravity/history',
+    'antigravity/idb-list',
+    'antigravity/mark-read',
+    'antigravity/model',
+    'antigravity/nav',
+    'antigravity/new',
+    'antigravity/react',
+    'antigravity/read',
+    'antigravity/rename',
+    'antigravity/revert',
+    'antigravity/send',
+    'antigravity/settings',
+    'antigravity/sidebar-toggle',
+    'antigravity/status',
+    'antigravity/storage-get',
+    'antigravity/storage-keys',
+    'antigravity/toggle-aux',
+    'antigravity/watch',
+    'chatgpt-app/ask',
+    'chatgpt-app/model',
+    'chatgpt-app/new',
+    'chatgpt-app/read',
+    'chatgpt-app/send',
+    'chatgpt-app/status',
+    'chatwise/ask',
+    'chatwise/export',
+    'chatwise/history',
+    'chatwise/model',
+    'chatwise/new',
+    'chatwise/read',
+    'chatwise/screenshot',
+    'chatwise/send',
+    'chatwise/status',
+    'codex/archive',
+    'codex/ask',
+    'codex/dump',
+    'codex/export',
+    'codex/extract-diff',
+    'codex/history',
+    'codex/model',
+    'codex/new',
+    'codex/pin',
+    'codex/projects',
+    'codex/read',
+    'codex/rename',
+    'codex/screenshot',
+    'codex/send',
+    'codex/status',
+    'codex/unpin',
+    'cursor/ask',
+    'cursor/composer',
+    'cursor/dump',
+    'cursor/export',
+    'cursor/extract-code',
+    'cursor/history',
+    'cursor/model',
+    'cursor/new',
+    'cursor/read',
+    'cursor/screenshot',
+    'cursor/send',
+    'cursor/status',
+    'discord-app/channels',
+    'discord-app/delete',
+    'discord-app/goto',
+    'discord-app/members',
+    'discord-app/read',
+    'discord-app/search',
+    'discord-app/send',
+    'discord-app/servers',
+    'discord-app/status',
+    'discord-app/thread-read',
+    'discord-app/threads',
+    'qoder/account',
+    'qoder/add-workspace',
+    'qoder/ask',
+    'qoder/credits',
+    'qoder/history',
+    'qoder/knowledge',
+    'qoder/marketplace',
+    'qoder/more-actions',
+    'qoder/new',
+    'qoder/open-editor',
+    'qoder/open-panel',
+    'qoder/prompt-enhance',
+    'qoder/read',
+    'qoder/search',
+    'qoder/send',
+    'qoder/settings',
+    'qoder/sidebar-toggle',
+    'qoder/status',
+    'qoder/view-all',
+    'trae-solo/automation-list',
+    'trae-solo/cookies',
+    'trae-solo/history',
+    'trae-solo/idb-list',
+    'trae-solo/mode',
+    'trae-solo/model',
+    'trae-solo/skill-category',
+    'trae-solo/skill-list',
+    'trae-solo/skill-search',
+    'trae-solo/status',
+    'trae-solo/storage-get',
+    'trae-solo/storage-keys',
+];
+function exceptionDiff(actual, expected) {
+    const actualSet = new Set(actual);
+    const expectedSet = new Set(expected);
+    return {
+        added: actual.filter(name => !expectedSet.has(name)),
+        missing: expected.filter(name => !actualSet.has(name)),
+    };
+}
+describe('hosted availability', () => {
+    it('derives decisions only from normalized strategy and domain metadata', () => {
+        expect(deriveHostedAvailability({ strategy: 'local', domain: 'localhost' }))
+            .toEqual({ mode: 'local-only', reason: 'local-tool' });
+        expect(deriveHostedAvailability({ strategy: 'ui', domain: 'localhost' }))
+            .toEqual({ mode: 'local-only', reason: 'desktop-app' });
+        expect(deriveHostedAvailability({ strategy: 'cookie', domain: 'example.com' }))
+            .toEqual({ mode: 'hosted' });
+        expect(deriveBrowserAvailability('bind'))
+            .toEqual({ mode: 'local-only', reason: 'browser-bind' });
+        expect(deriveBrowserAvailability('open')).toEqual({ mode: 'hosted' });
+    });
+    it('matches the reviewed local-only adapter exception sets exactly', () => {
+        const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+        const entries = JSON.parse(fs.readFileSync(path.join(root, 'cli-manifest.json'), 'utf8'));
+        const byReason = new Map([
+            ['local-tool', []],
+            ['desktop-app', []],
+        ]);
+        for (const entry of entries) {
+            const availability = deriveHostedAvailability(entry);
+            if (availability.mode === 'local-only') {
+                byReason.get(availability.reason)?.push(`${entry.site}/${entry.name}`);
+            }
+        }
+        const localTools = (byReason.get('local-tool') ?? []).sort();
+        const desktopApps = (byReason.get('desktop-app') ?? []).sort();
+        expect(exceptionDiff(localTools, EXPECTED_LOCAL_TOOLS)).toEqual({ added: [], missing: [] });
+        expect(exceptionDiff(desktopApps, EXPECTED_DESKTOP_APPS)).toEqual({ added: [], missing: [] });
+        expect(localTools).toHaveLength(19);
+        expect(desktopApps).toHaveLength(111);
+    });
+});

package/dist/src/hosted/browser-args.d.ts

@@ -0,0 +1,18 @@
+export declare class HostedBrowserHelp extends Error {
+    readonly output: string;
+    constructor(output: string);
+}
+export interface ParsedHostedBrowserStructure {
+    commandName?: string;
+    positionals: string[];
+    options: Record<string, unknown>;
+    session?: string;
+    window?: string;
+    profile?: string;
+}
+/**
+ * Parse the hosted browser argv with the exact canonical Commander grammar.
+ * The returned values are the values produced by Commander's action boundary;
+ * callers must not reinterpret the original argv with a second parser.
+ */
+export declare function parseHostedBrowserStructure(argv: readonly string[]): ParsedHostedBrowserStructure;

package/dist/src/hosted/browser-args.js

@@ -0,0 +1,152 @@
+import { Command, Option } from 'commander';
+import { browserCommandCatalog, browserOptionFlags, browserOptionValueParser, } from '../browser/command-catalog.js';
+import { CommanderStructuralError } from '../command-surface.js';
+export class HostedBrowserHelp extends Error {
+    output;
+    constructor(output) {
+        super('Hosted browser help requested');
+        this.output = output;
+        this.name = 'HostedBrowserHelp';
+    }
+}
+/**
+ * Parse the hosted browser argv with the exact canonical Commander grammar.
+ * The returned values are the values produced by Commander's action boundary;
+ * callers must not reinterpret the original argv with a second parser.
+ */
+export function parseHostedBrowserStructure(argv) {
+    const root = new Command('webcmd')
+        .option('--profile <name>', 'Chrome profile/context alias for browser runtime commands')
+        .enablePositionalOptions();
+    const browser = root
+        .command('browser')
+        .addOption(new Option('--session <name>', 'Internal — set automatically from the <session> positional').hideHelp())
+        .option('--window <mode>', 'Browser window mode: foreground or background')
+        .description('Browser control — navigate, click, type, extract, wait (no LLM needed)')
+        .usage('<session> <command> [options]')
+        .addHelpText('after', `
+<session> is a required positional: pass the name of the browser session every subcommand should operate on. Reuse the same name across calls to keep the tab/state alive; pick a different name to isolate parallel browser work.
+
+Examples:
+  $ webcmd browser work open https://x.com
+  $ webcmd browser work open https://x.com --window background
+  $ webcmd browser work click 12
+  $ webcmd browser work state
+  $ webcmd browser work tab list
+  $ webcmd browser work bind --page page-123
+  $ webcmd browser work unbind  # compatibility command; releases the Cloak session
+`);
+    let parsed;
+    const namespaces = new Map([['', browser]]);
+    const namespaceDescriptions = {
+        dialog: 'Handle a blocking JavaScript alert/confirm/prompt dialog',
+        get: 'Get page properties',
+        tab: 'Tab management — list, create, and close tabs in the browser session',
+    };
+    for (const contract of browserCommandCatalog) {
+        const parts = contract.command.split('/');
+        let parent = browser;
+        let path = '';
+        for (let index = 0; index < parts.length - 1; index += 1) {
+            path = path ? `${path}/${parts[index]}` : parts[index];
+            let namespace = namespaces.get(path);
+            if (!namespace) {
+                namespace = parent.command(parts[index]);
+                const description = namespaceDescriptions[path];
+                if (description)
+                    namespace.description(description);
+                namespaces.set(path, namespace);
+            }
+            parent = namespace;
+        }
+        const leafName = parts.at(-1);
+        const leaf = parent.command(leafName).description(contract.description);
+        for (const alias of contract.aliases)
+            leaf.alias(alias);
+        for (const positional of contract.positionals) {
+            const suffix = positional.variadic ? '...' : '';
+            leaf.argument(positional.required ? `<${positional.name}${suffix}>` : `[${positional.name}${suffix}]`, positional.description);
+        }
+        for (const option of contract.options) {
+            const flags = browserOptionFlags(option);
+            if (option.type === 'boolean') {
+                leaf.option(flags, option.description, option.default);
+                continue;
+            }
+            const commanderOption = new Option(flags, option.description);
+            if (option.choices?.length)
+                commanderOption.choices(option.choices);
+            if (option.default !== undefined)
+                commanderOption.default(String(option.default));
+            const valueParser = browserOptionValueParser(contract.command, option.name);
+            if (valueParser)
+                commanderOption.argParser(valueParser);
+            leaf.addOption(commanderOption);
+        }
+        leaf.action((...actionArgs) => {
+            const options = actionArgs[contract.positionals.length];
+            parsed = {
+                commandName: contract.command,
+                positionals: actionArgs.slice(0, contract.positionals.length).flatMap(value => {
+                    if (typeof value === 'string')
+                        return [value];
+                    if (Array.isArray(value))
+                        return value.filter((entry) => typeof entry === 'string');
+                    return [];
+                }),
+                options: { ...options },
+                ...readBrowserGlobals(root, browser),
+            };
+        });
+    }
+    let stderr = '';
+    let stdout = '';
+    const output = {
+        writeErr: (value) => { stderr += value; },
+        writeOut: (value) => { stdout += value; },
+    };
+    const configure = (command) => {
+        command.exitOverride().configureOutput(output);
+        for (const child of command.commands)
+            configure(child);
+    };
+    configure(root);
+    const browserAwareUsage = (command) => {
+        const ancestors = [];
+        let ancestor = command.parent;
+        while (ancestor) {
+            ancestors.unshift(ancestor === browser ? `${ancestor.name()} <session>` : ancestor.name());
+            ancestor = ancestor.parent;
+        }
+        return [...ancestors, command.name(), command.usage()].filter(Boolean).join(' ').trim();
+    };
+    const configureBrowserUsage = (command) => {
+        command.configureHelp({ commandUsage: browserAwareUsage });
+        for (const child of command.commands)
+            configureBrowserUsage(child);
+    };
+    configureBrowserUsage(browser);
+    try {
+        root.parse([...argv], { from: 'user' });
+    }
+    catch (error) {
+        const commander = error;
+        if (commander.code === 'commander.helpDisplayed')
+            throw new HostedBrowserHelp(stdout);
+        throw new CommanderStructuralError(stderr || `${typeof commander.message === 'string' ? commander.message : String(error)}\n`, typeof commander.exitCode === 'number' ? commander.exitCode : 1);
+    }
+    return parsed ?? {
+        positionals: [],
+        options: {},
+        ...readBrowserGlobals(root, browser),
+    };
+}
+function readBrowserGlobals(root, browser) {
+    const rootOptions = root.opts();
+    const browserOptions = browser.opts();
+    return {
+        ...(typeof browserOptions.session === 'string' ? { session: browserOptions.session } : {}),
+        ...(typeof browserOptions.window === 'string' ? { window: browserOptions.window } : {}),
+        ...(typeof rootOptions.profile === 'string' ? { profile: rootOptions.profile } : {}),
+    };
+}

package/dist/src/hosted/browser-args.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hosted/browser-args.test.js

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+import { browserCommandCatalog } from '../browser/command-catalog.js';
+import { rewriteBrowserArgv } from '../cli-argv-preprocess.js';
+import { createProgram } from '../cli.js';
+import { CommanderStructuralError } from '../command-surface.js';
+import { HostedBrowserHelp, parseHostedBrowserStructure, } from './browser-args.js';
+function findLocalBrowserLeaf(program, commandPath) {
+    const browser = program.commands.find(command => command.name() === 'browser');
+    if (!browser)
+        throw new Error('Local browser namespace is missing');
+    let leaf = browser;
+    for (const part of commandPath.split('/')) {
+        const child = leaf.commands.find(command => command.name() === part || command.aliases().includes(part));
+        if (!child)
+            throw new Error(`Local browser command is missing: ${commandPath}`);
+        leaf = child;
+    }
+    return { browser, leaf };
+}
+function flattenPositionals(values) {
+    return values.flatMap(value => {
+        if (typeof value === 'string')
+            return [value];
+        if (Array.isArray(value))
+            return value.filter((entry) => typeof entry === 'string');
+        return [];
+    });
+}
+function captureLocalBrowserValues(commandPath, argv) {
+    const program = createProgram('', '');
+    const contract = browserCommandCatalog.find(command => command.command === commandPath);
+    if (!contract)
+        throw new Error(`Browser contract is missing: ${commandPath}`);
+    const { browser, leaf } = findLocalBrowserLeaf(program, commandPath);
+    let parsed;
+    leaf.action((...actionArgs) => {
+        const options = actionArgs[contract.positionals.length];
+        const rootOptions = program.opts();
+        const browserOptions = browser.opts();
+        parsed = {
+            commandName: commandPath,
+            positionals: flattenPositionals(actionArgs.slice(0, contract.positionals.length)),
+            options: { ...options },
+            ...(typeof browserOptions.session === 'string' ? { session: browserOptions.session } : {}),
+            ...(typeof browserOptions.window === 'string' ? { window: browserOptions.window } : {}),
+            ...(typeof rootOptions.profile === 'string' ? { profile: rootOptions.profile } : {}),
+        };
+    });
+    const configure = (command) => {
+        command.exitOverride().configureOutput({ writeErr: () => undefined, writeOut: () => undefined });
+        for (const child of command.commands)
+            configure(child);
+    };
+    configure(program);
+    program.parse(rewriteBrowserArgv(argv), { from: 'user' });
+    if (!parsed)
+        throw new Error(`Local browser action did not run: ${commandPath}`);
+    return parsed;
+}
+function allPositionals(commandPath) {
+    const contract = browserCommandCatalog.find(command => command.command === commandPath);
+    return contract.positionals.flatMap(position => position.variadic
+        ? [`${position.name}-one`, `${position.name}-two`]
+        : [`${position.name}-value`]);
+}
+function parseHosted(argv) {
+    return parseHostedBrowserStructure(rewriteBrowserArgv(argv));
+}
+describe('hosted browser canonical Commander values', () => {
+    it('matches the actual local action boundary for every catalogued browser leaf', () => {
+        for (const contract of browserCommandCatalog) {
+            const argv = ['browser', 'work', ...contract.command.split('/'), ...allPositionals(contract.command)];
+            expect({ command: contract.command, parsed: parseHosted(argv) }).toEqual({
+                command: contract.command,
+                parsed: captureLocalBrowserValues(contract.command, argv),
+            });
+        }
+    });
+    it.each([
+        {
+            name: 'negative numeric required option value',
+            command: 'scroll',
+            tail: ['down', '--amount', '-5'],
+        },
+        {
+            name: 'dash-leading string option value',
+            command: 'state',
+            tail: ['--source', '-dash'],
+        },
+        {
+            name: 'equals option form',
+            command: 'eval',
+            tail: ['return 1', '--frame=-2'],
+        },
+        {
+            name: 'repeated string option uses the last value',
+            command: 'scroll',
+            tail: ['down', '--amount', '10', '--amount=-5'],
+        },
+        {
+            name: 'repeated boolean flags remain boolean',
+            command: 'screenshot',
+            tail: ['shot.png', '--full-page', '--full-page', '--width=10', '--height', '20'],
+        },
+        {
+            name: 'negative boolean option grammar',
+            command: 'verify',
+            tail: ['site/command', '--no-fixture', '--no-fixture'],
+        },
+        {
+            name: 'dash-leading positional after separator',
+            command: 'eval',
+            tail: ['--', '-script'],
+        },
+        {
+            name: 'variadic dash-leading positionals after separator',
+            command: 'upload',
+            tail: ['input[type=file]', '--', '-one.txt', '-two.txt'],
+        },
+        {
+            name: 'trailing namespace window is hoisted',
+            command: 'state',
+            tail: ['--window', 'background'],
+        },
+        {
+            name: 'equals namespace window before leaf',
+            command: 'state',
+            prefix: ['--window=foreground'],
+            tail: [],
+        },
+        {
+            name: 'repeated namespace window uses the last value',
+            command: 'state',
+            prefix: ['--window', 'foreground', '--window=background'],
+            tail: [],
+        },
+        {
+            name: 'string and boolean observation options retain canonical types',
+            command: 'network',
+            tail: ['--since', '-5', '--follow', '--failed', '--max-body=-10'],
+        },
+    ])('$name', ({ command, prefix = [], tail }) => {
+        const argv = ['browser', 'work', ...prefix, ...command.split('/'), ...tail];
+        expect(parseHosted(argv)).toEqual(captureLocalBrowserValues(command, argv));
+    });
+    it.each([
+        ['ordinary unknown option', ['browser', 'work', 'state', '--unknown']],
+        ['ordinary missing option value', ['browser', 'work', 'state', '--source']],
+        ['ordinary excess positional', ['browser', 'work', 'state', 'extra']],
+        ['missing required positional', ['browser', 'work', 'eval']],
+        ['help wins over unknown', ['browser', 'work', 'state', '--unknown', '--help']],
+        ['option missing value beats help', ['browser', 'work', 'state', '--help', '--source']],
+        ['invalid structurally-coerced screenshot dimension', ['browser', 'work', 'screenshot', '--width=-10']],
+        ['site-session is not a browser namespace option', ['browser', 'work', '--site-session', 'persistent', 'state']],
+        ['keep-tab is not a browser namespace option', ['browser', 'work', 'state', '--keep-tab', 'true']],
+    ])('retains exact local structural outcome: %s', (_name, argv) => {
+        const commandPath = argv.includes('eval') ? 'eval' : argv.includes('screenshot') ? 'screenshot' : 'state';
+        const capture = (run) => {
+            try {
+                run();
+                return { kind: 'success' };
+            }
+            catch (error) {
+                if (error instanceof HostedBrowserHelp)
+                    return { kind: 'help', output: error.output, exitCode: 0 };
+                if (error instanceof CommanderStructuralError) {
+                    return { kind: 'structural', output: error.output, exitCode: error.exitCode };
+                }
+                const commander = error;
+                return {
+                    kind: commander.code === 'commander.helpDisplayed' ? 'help' : 'structural',
+                    exitCode: typeof commander.exitCode === 'number' ? commander.exitCode : 1,
+                };
+            }
+        };
+        const local = capture(() => captureLocalBrowserValues(commandPath, argv));
+        const hosted = capture(() => parseHosted(argv));
+        expect({ kind: hosted.kind, exitCode: hosted.exitCode }).toEqual({ kind: local.kind, exitCode: local.exitCode });
+        if (hosted.kind === 'structural')
+            expect(hosted.output).toBeDefined();
+    });
+});

package/dist/src/hosted/client.d.ts

@@ -1,12 +1,17 @@
 import { CliError, type ExitCode } from '../errors.js';
-import type { HostedBrowserActionRequest, HostedBrowserActionResponse, HostedBrowserFinishRequest, HostedBrowserFinishResponse, HostedBrowserRunActionInput, HostedBrowserRunActionResponse, HostedBrowserRunRequest, HostedBrowserRunResponse, HostedExecuteResponse, HostedManifest } from './types.js';
+import type { HostedBrowserActionRequest, HostedBrowserActionResponse, HostedBrowserFinishRequest, HostedBrowserFinishResponse, HostedBrowserRunActionInput, HostedBrowserRunActionResponse, HostedBrowserRunRequest, HostedBrowserRunResponse, HostedExecution, HostedExecuteResponse, HostedPrepareExecutionResponse, HostedProfilesResponse, HostedUploadArtifactResponse, HostedManifest, HostedTraceReceipt } from './types.js';
 export interface HostedClientOptions {
     apiBaseUrl: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
 }
 export declare class HostedClientError extends CliError {
-    constructor(code: string, message: string, help?: string, exitCode?: ExitCode);
+    readonly execution?: HostedExecution;
+    readonly trace?: HostedTraceReceipt;
+    constructor(code: string, message: string, help?: string, exitCode?: ExitCode, metadata?: {
+        execution?: HostedExecution;
+        trace?: HostedTraceReceipt;
+    });
 }
 export declare class HostedClient {
     private readonly apiBaseUrl;
@@ -15,6 +20,7 @@ export declare class HostedClient {
     constructor(options: HostedClientOptions);
     getMe(): Promise<unknown>;
     getManifest(): Promise<HostedManifest>;
+    listProfiles(): Promise<HostedProfilesResponse>;
     execute(input: {
         command: string;
         args: Record<string, unknown>;
@@ -22,9 +28,32 @@ export declare class HostedClient {
         trace?: string;
         profile?: string;
     }): Promise<HostedExecuteResponse>;
+    prepareExecution(input: {
+        command: string;
+    }): Promise<HostedPrepareExecutionResponse>;
+    uploadExecutionArtifact(input: {
+        executionId: string;
+        argument: string;
+        filename: string;
+        contentType: string;
+        body: Uint8Array;
+    }): Promise<HostedUploadArtifactResponse>;
+    runPreparedExecution(input: {
+        executionId: string;
+        command: string;
+        args: Record<string, unknown>;
+        format?: string;
+        trace?: string;
+        profile?: string;
+    }): Promise<HostedExecuteResponse>;
+    downloadExecutionArtifact(input: {
+        executionId: string;
+        artifactId: string;
+    }): Promise<Uint8Array>;
     startBrowserRun(session: string, input: HostedBrowserRunRequest): Promise<HostedBrowserRunResponse>;
     browserAction(session: string, executionId: string, input: HostedBrowserActionRequest): Promise<HostedBrowserActionResponse>;
     finishBrowserRun(session: string, executionId: string, input: HostedBrowserFinishRequest): Promise<HostedBrowserFinishResponse>;
     runBrowserAction(session: string, input: HostedBrowserRunActionInput): Promise<HostedBrowserRunActionResponse>;
+    executeBrowserCommand(session: string, input: HostedBrowserRunActionInput): Promise<HostedBrowserRunActionResponse>;
     private request;
 }