@agentrhq/webcmd 0.2.5 → 0.3.0

package/clis/_shared/site-auth.js

@@ -72,7 +72,7 @@ export function registerSiteAuthCommands(config) {
         ? { refresh: async (page, kwargs) => normalizeRefreshResult(await config.refresh(page, kwargs)) }
         : {}),
     },
-    func: async (page) => tryProbe(config, page, 'identity'),
+    func: async (page) => [await tryProbe(config, page, 'identity')],
   });
 
   cli({
@@ -92,7 +92,7 @@ export function registerSiteAuthCommands(config) {
     columns: ['status', ...commandColumns(config)],
     func: async (page, kwargs) => {
       try {
-        return { status: 'already_logged_in', ...await tryProbe(config, page, 'identity') };
+        return [{ status: 'already_logged_in', ...await tryProbe(config, page, 'identity') }];
       } catch (error) {
         if (!isAuthRequired(error)) throw error;
       }
@@ -106,7 +106,7 @@ export function registerSiteAuthCommands(config) {
         await page.wait(Math.min(POLL_INTERVAL_MS / 1000, Math.max(0.2, (deadline - Date.now()) / 1000)));
         try {
           const identity = await tryProbe(config, page, 'poll');
-          return { status: 'login_complete', ...identity };
+          return [{ status: 'login_complete', ...identity }];
         } catch (error) {
           if (!isAuthRequired(error)) throw error;
           lastAuthMessage = getErrorMessage(error);

package/clis/_shared/site-auth.test.js

@@ -47,11 +47,11 @@ describe('site auth command helper', () => {
     const cmd = getRegistry().get('auth-helper-whoami/whoami');
     const page = pageMock();
 
-    await expect(cmd.func(page, {})).resolves.toEqual({
+    await expect(cmd.func(page, {})).resolves.toEqual([{
       logged_in: true,
       site: 'auth-helper-whoami',
       username: 'alice',
-    });
+    }]);
     expect(page.goto).not.toHaveBeenCalled();
   });
 
@@ -70,12 +70,12 @@ describe('site auth command helper', () => {
     const cmd = getRegistry().get('auth-helper-login/login');
     const page = pageMock();
 
-    await expect(cmd.func(page, { timeout: 1 })).resolves.toEqual({
+    await expect(cmd.func(page, { timeout: 1 })).resolves.toEqual([{
       status: 'login_complete',
       logged_in: true,
       site: 'auth-helper-login',
       username: 'alice',
-    });
+    }]);
     expect(page.goto).toHaveBeenCalledWith('https://example.com/login');
     expect(page.wait).toHaveBeenCalled();
     expect(poll).toHaveBeenCalledTimes(2);

package/clis/slock/whoami.test.js

@@ -14,10 +14,10 @@ function makePage(authMe, status = 200) {
 describe('slock whoami', () => {
   const command = getRegistry().get('slock/whoami');
 
-  it('returns a normalized identity object from /auth/me on 200', async () => {
+  it('returns a normalized identity row from /auth/me on 200', async () => {
     const page = makePage({ id: 'u1', name: 'Alice', email: 'a@b.c' });
     const identity = await command.func(page, {});
-    expect(identity).toEqual({ logged_in: true, site: 'slock', id: 'u1', name: 'Alice', email: 'a@b.c' });
+    expect(identity).toEqual([{ logged_in: true, site: 'slock', id: 'u1', name: 'Alice', email: 'a@b.c' }]);
     expect(page.goto).toHaveBeenCalled();
   });
 });

package/dist/src/browser/daemon-client.d.ts

@@ -4,7 +4,7 @@
  * Provides a typed send() function that posts a Command and returns a Result.
  */
 import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, type BrowserProfileStatus, type DaemonHealth, type DaemonStatus } from './daemon-transport.js';
-import type { BrowserRuntimeCommand, BrowserRuntimeResult } from './protocol.js';
+import type { BrowserRuntimeCommand, BrowserRuntimeResult, BrowserWindowMode } from './protocol.js';
 export declare function setDaemonCommandTimeoutSeconds(seconds: number | null): void;
 export type DaemonCommand = BrowserRuntimeCommand;
 export type DaemonResult = BrowserRuntimeResult;
@@ -31,4 +31,5 @@ export declare function bindTab(session: string, opts?: {
     preferredContextId?: string;
     page?: string;
     index?: number;
+    windowMode?: BrowserWindowMode;
 }): Promise<unknown>;

package/dist/src/browser/runtime/local-cloak/actions.js

@@ -44,6 +44,7 @@ async function resolveLease(manager, command) {
         siteSession: command.siteSession,
         idleTimeout: command.idleTimeout,
         freshPage: command.freshPage,
+        windowMode: command.windowMode,
     });
 }
 function execTarget(page, frameIndex, pageId) {
@@ -134,11 +135,12 @@ export async function dispatchCloakAction(manager, command) {
                             siteSession: command.siteSession,
                             idleTimeout: command.idleTimeout,
                             url: command.url,
+                            windowMode: command.windowMode,
                         });
                         return { id: command.id, ok: true, data: { title: await lease.page.title(), url: lease.page.url() }, page: lease.pageId };
                     }
                     case 'select': {
-                        const lease = await manager.selectPage({ profileId: commandProfileId(manager, command), pageId: command.page, index: command.index });
+                        const lease = await manager.selectPage({ profileId: commandProfileId(manager, command), pageId: command.page, index: command.index, windowMode: command.windowMode });
                         if (!lease)
                             return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: 'Tab not found' };
                         return { id: command.id, ok: true, data: { selected: true, url: lease.page.url() }, page: lease.pageId };
@@ -217,6 +219,7 @@ export async function dispatchCloakAction(manager, command) {
                         surface: command.surface,
                         siteSession: command.siteSession,
                         idleTimeout: command.idleTimeout,
+                        windowMode: command.windowMode,
                         pageId: command.page,
                         index: command.index,
                     });

package/dist/src/browser/runtime/local-cloak/provider.test.js

@@ -231,6 +231,42 @@ describe('LocalCloakRuntimeProvider', () => {
             .resolves.toMatchObject({ id: 'close', ok: true, data: { closed: created.page } });
         expect(pages[1].close).toHaveBeenCalled();
     });
+    it('does not bring selected tabs to front in background window mode', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'work', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({
+            id: 'select',
+            action: 'tabs',
+            op: 'select',
+            session: 'work',
+            surface: 'browser',
+            page: created.page,
+            profileId: 'default',
+            windowMode: 'background',
+        })).resolves.toMatchObject({ id: 'select', ok: true });
+        expect(pages[1].bringToFront).not.toHaveBeenCalled();
+    });
+    it('does not bring bound tabs to front in background window mode', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'source', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({
+            id: 'bind',
+            action: 'bind',
+            session: 'target',
+            surface: 'browser',
+            page: created.page,
+            profileId: 'default',
+            windowMode: 'background',
+        })).resolves.toMatchObject({ id: 'bind', ok: true });
+        expect(pages[1].bringToFront).not.toHaveBeenCalled();
+    });
+    it('brings bound tabs to front by default', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'source', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'target', surface: 'browser', page: created.page, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'bind', ok: true });
+        expect(pages[1].bringToFront).toHaveBeenCalledOnce();
+    });
     it('closes a window by page identity when command.page is provided', async () => {
         const { provider, pages } = makeProviderWithFakePage();
         const first = await provider.dispatch({ id: 'first', action: 'navigate', session: 'first', surface: 'browser', url: 'https://first.example/', profileId: 'default' });

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -1,6 +1,6 @@
 import type { BrowserContext, Page as PlaywrightPage } from 'playwright-core';
 import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
-import type { BrowserSurface, SiteSessionMode } from '../../protocol.js';
+import type { BrowserSurface, BrowserWindowMode, SiteSessionMode } from '../../protocol.js';
 import { CloakNetworkCapture } from './network.js';
 export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
 export type RecoverLockedProfile = (userDataDir: string) => Promise<boolean>;
@@ -10,6 +10,7 @@ export interface SessionKeyInput {
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
     idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
     /** Discard the existing leased page (if any) and create a new one under the same lease. */
     freshPage?: boolean;
 }
@@ -61,7 +62,7 @@ export declare class CloakSessionManager {
     newPage(input: SessionKeyInput & {
         url?: string;
     }): Promise<CloakPageLease>;
-    selectPage(input: Pick<SessionKeyInput, 'profileId'> & {
+    selectPage(input: Pick<SessionKeyInput, 'profileId' | 'windowMode'> & {
         pageId?: string;
         index?: number;
     }): Promise<CloakPageLease | null>;

package/dist/src/browser/runtime/local-cloak/session-manager.js

@@ -152,7 +152,8 @@ export class CloakSessionManager {
         if (!match)
             return null;
         const [leaseKey, entry] = match;
-        await entry.page.bringToFront?.().catch(() => { });
+        if (input.windowMode !== 'background')
+            await entry.page.bringToFront?.().catch(() => { });
         runtime.selectedPageId = entry.pageId;
         runtime.lastSeenAt = Date.now();
         return { profileId, leaseKey, context: runtime.context, page: entry.page, pageId: entry.pageId };
@@ -183,7 +184,8 @@ export class CloakSessionManager {
         entry.siteSession = input.siteSession;
         entry.idleTimeout = input.idleTimeout;
         runtime.pages.set(canonicalKey, entry);
-        await entry.page.bringToFront?.().catch(() => { });
+        if (input.windowMode !== 'background')
+            await entry.page.bringToFront?.().catch(() => { });
         this.refreshIdleTimer(runtime, canonicalKey, entry);
         runtime.selectedPageId = entry.pageId;
         runtime.lastSeenAt = Date.now();

package/dist/src/cli.js

@@ -1022,11 +1022,12 @@ Examples:
             const profileSelection = getBrowserProfileSelection(command);
             const contextId = profileSelection?.contextId;
             const routing = profileRouteParams(profileSelection);
+            const windowMode = getBrowserWindowMode(command, 'foreground');
             try {
                 const { BrowserBridge } = await import('./browser/index.js');
                 const bridge = new BrowserBridge();
-                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...routing });
-                await fn({ session, contextId, routing }, opts);
+                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...routing, windowMode });
+                await fn({ session, contextId, routing, windowMode }, opts);
             }
             catch (err) {
                 if (err instanceof BrowserCommandError) {
@@ -1044,7 +1045,7 @@ Examples:
         .description('Bind an existing Cloak runtime tab to the browser session named by <session>')
         .option('--page <id>', 'Cloak tab page id from `webcmd browser <session> tab list`')
         .option('--index <n>', 'Cloak tab index from `webcmd browser <session> tab list`')
-        .action(browserSessionCommandAction(async ({ session, contextId, routing }, opts) => {
+        .action(browserSessionCommandAction(async ({ session, contextId, routing, windowMode }, opts) => {
         const page = typeof opts.page === 'string' && opts.page.trim() ? opts.page.trim() : undefined;
         const rawIndex = typeof opts.index === 'string' && opts.index.trim() ? opts.index.trim() : undefined;
         if ((page && rawIndex) || (!page && !rawIndex)) {
@@ -1054,7 +1055,7 @@ Examples:
             throw new BrowserCommandError('--index must be a non-negative integer.', 'invalid_request');
         }
         const index = rawIndex === undefined ? undefined : Number.parseInt(rawIndex, 10);
-        const data = await bindTab(session, { ...routing, ...(page && { page }), ...(index !== undefined && { index }) });
+        const data = await bindTab(session, { ...routing, ...(page && { page }), ...(index !== undefined && { index }), windowMode });
         saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
         console.log(JSON.stringify({ session, ...((data && typeof data === 'object') ? data : { data }) }, null, 2));
     }));

package/dist/src/cli.test.js

@@ -1109,8 +1109,8 @@ describe('browser tab targeting commands', () => {
     it('binds an existing Cloak tab by page id into a browser session', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind', '--page', 'tab-2']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
-        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2', windowMode: 'foreground' });
         const out = lastJsonLog();
         expect(out.session).toBe('test');
         expect(out.url).toBe('https://user.example/inbox');
@@ -1118,11 +1118,17 @@ describe('browser tab targeting commands', () => {
     it('binds an existing Cloak tab by index into a browser session', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind', '--index', '1']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
-        expect(mockBindTab).toHaveBeenCalledWith('test', { index: 1 });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { index: 1, windowMode: 'foreground' });
         const out = lastJsonLog();
         expect(out.session).toBe('test');
     });
+    it('passes background window mode when binding a Cloak tab', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', '--window', 'background', 'bind', '--page', 'tab-2']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'background' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2', windowMode: 'background' });
+    });
     it('requires an explicit Cloak tab target for bind', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind']);
@@ -1237,7 +1243,7 @@ describe('browser tab targeting commands', () => {
     it('unbinds a session through the daemon close-window command', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'unbind']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
         expect(mockSendCommand).toHaveBeenCalledWith('close-window', { session: 'test', surface: 'browser' });
         const out = lastJsonLog();
         expect(out).toEqual({ unbound: true, session: 'test' });

package/dist/src/commands/auth.js

@@ -117,9 +117,10 @@ function safeIdentityValue(value) {
     return '';
 }
 function identitySummary(result) {
-    if (!result || typeof result !== 'object' || Array.isArray(result))
+    const first = Array.isArray(result) ? result[0] : result;
+    if (!first || typeof first !== 'object' || Array.isArray(first))
         return '';
-    const row = result;
+    const row = first;
     const blocked = /(?:email|phone|real.?name|first.?name|last.?name|cookie|token|session|secret|password|csrf|jwt|bearer|wt2)/i;
     for (const key of ['username', 'handle', 'user_id', 'id', 'name', 'nickname', 'user_type', 'url']) {
         if (blocked.test(key))

package/dist/src/commands/auth.test.js

@@ -74,12 +74,12 @@ describe('auth status collection', () => {
     });
     it('runs full whoami with --full and returns a safe identity summary', async () => {
         registerWhoami('gamma', {
-            identity: {
-                logged_in: true,
-                site: 'gamma',
-                email: 'hidden@example.com',
-                username: 'public-handle',
-            },
+            identity: [{
+                    logged_in: true,
+                    site: 'gamma',
+                    email: 'hidden@example.com',
+                    username: 'public-handle',
+                }],
         });
         const rows = await collectAuthStatus({ sites: 'gamma', full: true });
         expect(rows).toEqual([

package/dist/src/generate-release-notes-cli.test.js

@@ -68,6 +68,11 @@ describe('runGenerateReleaseNotes', () => {
                 '## Highlights',
                 '- Better summaries.',
                 '',
+                '## Contributors',
+                '<a href="https://github.com/alice" title="@alice"><img src="https://github.com/alice.png?size=64" width="64" height="64" alt="@alice" /></a>',
+                '',
+                '[@alice](https://github.com/alice)',
+                '',
             ].join('\n'),
             stderr: '',
         });

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

@@ -0,0 +1,9 @@
+import type { HostedCommand } from './types.js';
+export interface ParsedHostedInvocation {
+    args: Record<string, unknown>;
+    format: string;
+    trace: string;
+    profile?: string;
+    help: boolean;
+}
+export declare function parseHostedInvocation(command: HostedCommand, argv: string[]): ParsedHostedInvocation;

package/dist/src/hosted/args.js

@@ -0,0 +1,101 @@
+import { ArgumentError } from '../errors.js';
+export function parseHostedInvocation(command, argv) {
+    const args = {};
+    const positional = command.args.filter((arg) => arg.positional);
+    const named = new Map(command.args.filter((arg) => !arg.positional).map((arg) => [arg.name, arg]));
+    let positionalIndex = 0;
+    let format = String(command.defaultFormat || 'table');
+    let trace = 'off';
+    let profile;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--') {
+            for (const rest of argv.slice(i + 1)) {
+                const arg = positional[positionalIndex++];
+                if (!arg)
+                    throw new ArgumentError(`Unexpected positional argument: ${rest}`);
+                args[arg.name] = coerceValue(rest, arg.type);
+            }
+            break;
+        }
+        if (token === '-h' || token === '--help') {
+            help = true;
+            continue;
+        }
+        if (token === '-f' || token === '--format') {
+            format = readValue(argv, ++i, token);
+            continue;
+        }
+        if (token === '--trace') {
+            trace = readValue(argv, ++i, token);
+            continue;
+        }
+        if (token === '--profile') {
+            profile = readValue(argv, ++i, token);
+            continue;
+        }
+        if (token.startsWith('--')) {
+            const eqIndex = token.indexOf('=');
+            const rawName = token.slice(2, eqIndex === -1 ? undefined : eqIndex);
+            const arg = named.get(rawName);
+            if (!arg)
+                throw new ArgumentError(`Unknown option for hosted command ${command.command}: --${rawName}`);
+            const inlineValue = eqIndex === -1 ? undefined : token.slice(eqIndex + 1);
+            if (arg.type === 'bool' || arg.type === 'boolean') {
+                args[arg.name] = inlineValue === undefined ? true : coerceValue(inlineValue, arg.type);
+            }
+            else {
+                args[arg.name] = coerceValue(inlineValue ?? readValue(argv, ++i, token), arg.type);
+            }
+            continue;
+        }
+        const arg = positional[positionalIndex++];
+        if (!arg)
+            throw new ArgumentError(`Unexpected positional argument: ${token}`);
+        args[arg.name] = coerceValue(token, arg.type);
+    }
+    for (const arg of command.args) {
+        if (args[arg.name] === undefined && arg.default !== undefined)
+            args[arg.name] = arg.default;
+        if (arg.required && args[arg.name] === undefined) {
+            throw new ArgumentError(`Missing required argument for hosted command ${command.command}: ${arg.name}`);
+        }
+    }
+    return {
+        args,
+        format,
+        trace,
+        ...(profile ? { profile } : {}),
+        help,
+    };
+}
+function readValue(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined || value.startsWith('--')) {
+        throw new ArgumentError(`${flag} requires a value.`);
+    }
+    return value;
+}
+function coerceValue(value, type) {
+    if (type === 'int') {
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsed))
+            throw new ArgumentError(`Expected integer value, got "${value}".`);
+        return parsed;
+    }
+    if (type === 'number') {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed))
+            throw new ArgumentError(`Expected number value, got "${value}".`);
+        return parsed;
+    }
+    if (type === 'bool' || type === 'boolean') {
+        if (value === 'true' || value === '1')
+            return true;
+        if (value === 'false' || value === '0')
+            return false;
+        throw new ArgumentError(`Expected boolean value, got "${value}".`);
+    }
+    return value;
+}

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

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

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { parseHostedInvocation } from './args.js';
+const command = {
+    site: 'github',
+    name: 'search',
+    command: 'github/search',
+    description: 'Search GitHub',
+    access: 'read',
+    strategy: 'PUBLIC',
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, type: 'string' },
+        { name: 'limit', type: 'int', default: 10 },
+        { name: 'include-forks', type: 'boolean', default: false },
+    ],
+    columns: ['name'],
+};
+describe('parseHostedInvocation', () => {
+    it('parses positional args, value flags, boolean flags, and output options', () => {
+        expect(parseHostedInvocation(command, ['webcmd', '--limit', '5', '--include-forks', '-f', 'json', '--trace', 'on']))
+            .toEqual({
+            args: {
+                query: 'webcmd',
+                limit: 5,
+                'include-forks': true,
+            },
+            format: 'json',
+            trace: 'on',
+            help: false,
+        });
+    });
+    it('rejects missing required positional args', () => {
+        expect(() => parseHostedInvocation(command, [])).toThrow('Missing required argument');
+    });
+});

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

@@ -0,0 +1,30 @@
+import { CliError, type ExitCode } from '../errors.js';
+import type { HostedBrowserActionRequest, HostedBrowserActionResponse, HostedBrowserFinishRequest, HostedBrowserFinishResponse, HostedBrowserRunActionInput, HostedBrowserRunActionResponse, HostedBrowserRunRequest, HostedBrowserRunResponse, HostedExecuteResponse, HostedManifest } 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);
+}
+export declare class HostedClient {
+    private readonly apiBaseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(options: HostedClientOptions);
+    getMe(): Promise<unknown>;
+    getManifest(): Promise<HostedManifest>;
+    execute(input: {
+        command: string;
+        args: Record<string, unknown>;
+        format?: string;
+        trace?: string;
+        profile?: string;
+    }): Promise<HostedExecuteResponse>;
+    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>;
+    private request;
+}

package/dist/src/hosted/client.js

@@ -0,0 +1,122 @@
+import { CliError, EXIT_CODES } from '../errors.js';
+export class HostedClientError extends CliError {
+    constructor(code, message, help, exitCode = EXIT_CODES.GENERIC_ERROR) {
+        super(code, message, help, exitCode);
+    }
+}
+export class HostedClient {
+    apiBaseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        this.apiBaseUrl = options.apiBaseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async getMe() {
+        return this.request('/v1/me');
+    }
+    async getManifest() {
+        const body = await this.request('/v1/manifest');
+        if (!body.manifest || !Array.isArray(body.manifest.commands)) {
+            throw new HostedClientError('HOSTED_PROTOCOL', 'Webcmd Cloud returned an invalid manifest.');
+        }
+        return body.manifest;
+    }
+    async execute(input) {
+        return this.request('/v1/execute', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async startBrowserRun(session, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async browserAction(session, executionId, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs/${encodeURIComponent(executionId)}/actions`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async finishBrowserRun(session, executionId, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs/${encodeURIComponent(executionId)}/finish`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async runBrowserAction(session, input) {
+        const { command, trace, windowMode, action, profile, args } = input;
+        const run = await this.startBrowserRun(session, {
+            command,
+            args,
+            ...(profile !== undefined ? { profile } : {}),
+            ...(windowMode !== undefined ? { windowMode } : {}),
+            ...(trace !== undefined ? { trace } : {}),
+        });
+        try {
+            const actionResponse = await this.browserAction(session, run.run.executionId, {
+                action,
+                args,
+                ...(profile !== undefined ? { profile } : {}),
+            });
+            const finished = await this.finishBrowserRun(session, run.run.executionId, {
+                status: 'succeeded',
+                ...(profile !== undefined ? { profile } : {}),
+            });
+            return {
+                ...actionResponse,
+                run: run.run,
+                execution: finished.execution,
+            };
+        }
+        catch (error) {
+            await this.finishBrowserRun(session, run.run.executionId, {
+                status: 'failed',
+                errorCode: error instanceof HostedClientError ? error.code : 'HOSTED_BROWSER_ACTION_FAILED',
+                ...(profile !== undefined ? { profile } : {}),
+            }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async request(path, init = {}) {
+        const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+            ...init,
+            headers: {
+                accept: 'application/json',
+                ...(init.body ? { 'content-type': 'application/json' } : {}),
+                authorization: `Bearer ${this.apiKey}`,
+                ...(init.headers ?? {}),
+            },
+        });
+        const text = await response.text();
+        const body = text ? parseJson(text) : {};
+        if (!response.ok || isHostedError(body)) {
+            const error = isHostedError(body)
+                ? body.error
+                : { code: `HTTP_${response.status}`, message: `Webcmd Cloud request failed with HTTP ${response.status}.` };
+            throw new HostedClientError(error.code || `HTTP_${response.status}`, error.message || `Webcmd Cloud request failed with HTTP ${response.status}.`, error.help ?? error.hint, normalizeExitCode(error.exitCode, response.status === 401 ? EXIT_CODES.NOPERM : EXIT_CODES.GENERIC_ERROR));
+        }
+        return body;
+    }
+}
+function normalizeExitCode(value, fallback) {
+    const allowed = new Set(Object.values(EXIT_CODES));
+    return value !== undefined && allowed.has(value) ? value : fallback;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HostedClientError('HOSTED_PROTOCOL', 'Webcmd Cloud returned non-JSON response.');
+    }
+}
+function isHostedError(value) {
+    return !!value
+        && typeof value === 'object'
+        && value.ok === false
+        && typeof value.error === 'object';
+}

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

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