@agentrhq/webcmd 0.4.1 → 0.4.3

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { HostedClient } from './client.js';
+import { HostedClient, resolveWorkspace } from './client.js';
 const invalidTraceUrlCases = [
     {
         name: 'raw absolute Kernel URL with token',
@@ -170,7 +170,7 @@ describe('HostedClient', () => {
         const profile = {
             id: 'profile_work',
             name: 'Work',
-            userId: 'user_64256',
+            workspace: 'user_64256',
             default: false,
             status: 'available',
             createdAt: '2026-07-08T00:00:00.000Z',
@@ -187,34 +187,16 @@ describe('HostedClient', () => {
                     ...(init?.body ? { body: String(init.body) } : {}),
                 });
                 const path = new URL(String(url)).pathname;
-                if (path === '/v1/profiles' && init?.method === 'POST') {
-                    return new Response(JSON.stringify({ ok: true, profile }), { status: 201 });
-                }
                 if (path.startsWith('/v1/profiles/') && init?.method === 'DELETE') {
                     return new Response(JSON.stringify({ ok: true, deleted: true }));
                 }
-                if (path.startsWith('/v1/profiles/')) {
-                    return new Response(JSON.stringify({ ok: true, profile }));
-                }
                 return new Response(JSON.stringify({ ok: true, profiles: [profile] }));
             },
         });
-        await expect(client.listProfiles({ name: 'Work', userId: 'user_64256' }))
-            .resolves.toEqual({ ok: true, profiles: [profile] });
-        await expect(client.createProfile({ name: 'Work', userId: 'user_64256' }))
-            .resolves.toMatchObject({ profile: { id: 'profile_work', status: 'available' } });
-        await expect(client.getProfile('profile_work')).resolves.toMatchObject({
-            profile: { id: 'profile_work' },
-        });
+        await expect(client.listProfiles()).resolves.toEqual({ ok: true, profiles: [profile] });
         await expect(client.deleteProfile('profile/work')).resolves.toEqual({ ok: true, deleted: true });
         expect(requests).toEqual([
-            { url: 'https://api.example.com/v1/profiles?name=Work&userId=user_64256', method: 'GET' },
-            {
-                url: 'https://api.example.com/v1/profiles',
-                method: 'POST',
-                body: JSON.stringify({ name: 'Work', userId: 'user_64256' }),
-            },
-            { url: 'https://api.example.com/v1/profiles/profile_work', method: 'GET' },
+            { url: 'https://api.example.com/v1/profiles', method: 'GET' },
             { url: 'https://api.example.com/v1/profiles/profile%2Fwork', method: 'DELETE' },
         ]);
     });
@@ -222,12 +204,12 @@ describe('HostedClient', () => {
         { name: 'private provider field', change: { kernelProfileId: 'private' } },
         { name: 'missing updatedAt', change: { updatedAt: undefined } },
         { name: 'non-nullable name shape', change: { name: 7 } },
-        { name: 'non-nullable user ID shape', change: { userId: false } },
+        { name: 'non-nullable workspace shape', change: { workspace: false } },
     ])('rejects a hosted profile with $name', async ({ change }) => {
         const profile = {
             id: 'profile_work',
             name: null,
-            userId: null,
+            workspace: null,
             default: false,
             status: 'pending',
             createdAt: '2026-07-08T00:00:00.000Z',
@@ -850,4 +832,77 @@ describe('HostedClient', () => {
             },
         ]);
     });
+    it('attaches the workspace header when a workspace is configured', async () => {
+        const requests = [];
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            workspace: resolveWorkspace([], { WEBCMD_WORKSPACE: 'user_64256' }),
+            fetchImpl: async (_url, init) => {
+                requests.push({ workspace: new Headers(init?.headers).get('x-webcmd-workspace') });
+                return new Response(JSON.stringify({
+                    ok: true,
+                    result: [],
+                    execution: { id: 'exec_1', command: 'github/whoami', status: 'succeeded' },
+                }), { status: 200 });
+            },
+        });
+        await client.execute({ command: 'github/whoami', args: {} });
+        expect(requests).toEqual([{ workspace: 'user_64256' }]);
+    });
+    it('attaches the workspace header for the --workspace=<value> equals form', async () => {
+        const requests = [];
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            workspace: resolveWorkspace(['--workspace=user_64256'], {}),
+            fetchImpl: async (_url, init) => {
+                requests.push({ workspace: new Headers(init?.headers).get('x-webcmd-workspace') });
+                return new Response(JSON.stringify({
+                    ok: true,
+                    result: [],
+                    execution: { id: 'exec_1', command: 'github/whoami', status: 'succeeded' },
+                }), { status: 200 });
+            },
+        });
+        await client.execute({ command: 'github/whoami', args: {} });
+        expect(requests).toEqual([{ workspace: 'user_64256' }]);
+    });
+    it('omits the workspace header when no workspace is configured', async () => {
+        const requests = [];
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            fetchImpl: async (_url, init) => {
+                requests.push({ workspace: new Headers(init?.headers).get('x-webcmd-workspace') });
+                return new Response(JSON.stringify({
+                    ok: true,
+                    result: [],
+                    execution: { id: 'exec_1', command: 'github/whoami', status: 'succeeded' },
+                }), { status: 200 });
+            },
+        });
+        await client.execute({ command: 'github/whoami', args: {} });
+        expect(requests).toEqual([{ workspace: null }]);
+    });
+});
+describe('resolveWorkspace', () => {
+    it('returns the --workspace flag value when present', () => {
+        expect(resolveWorkspace(['--workspace', 'flagws'], {})).toBe('flagws');
+    });
+    it('returns the --workspace=<value> flag value when present', () => {
+        expect(resolveWorkspace(['--workspace=user_64256'], {})).toBe('user_64256');
+    });
+    it('--workspace overrides the env var', () => {
+        expect(resolveWorkspace(['--workspace', 'flagws'], { WEBCMD_WORKSPACE: 'envws' })).toBe('flagws');
+    });
+    it('falls back to WEBCMD_WORKSPACE when no flag is present', () => {
+        expect(resolveWorkspace([], { WEBCMD_WORKSPACE: 'envws' })).toBe('envws');
+    });
+    it('trims WEBCMD_WORKSPACE', () => {
+        expect(resolveWorkspace([], { WEBCMD_WORKSPACE: '  envws  ' })).toBe('envws');
+    });
+    it('returns undefined when neither --workspace nor WEBCMD_WORKSPACE is set', () => {
+        expect(resolveWorkspace([], {})).toBeUndefined();
+    });
 });

package/dist/src/hosted/runner.js

@@ -15,7 +15,7 @@ import { StreamWriteError, writeToStream } from '../stream-write.js';
 import { PKG_VERSION } from '../version.js';
 import { getCompletionScriptFast } from '../completion-fast.js';
 import { browserCommandCatalog } from '../browser/command-catalog.js';
-import { HostedClient, HostedClientError } from './client.js';
+import { HostedClient, HostedClientError, resolveWorkspace } from './client.js';
 import { parseHostedInvocation } from './args.js';
 import { HostedBrowserHelp, parseHostedBrowserStructure } from './browser-args.js';
 import { materializeHostedOutputs, prepareHostedFiles, rewriteHostedOutputResultPaths } from './files.js';
@@ -53,6 +53,7 @@ export async function runHostedCli(argv, opts = {}) {
         const client = new HostedClient({
             apiBaseUrl: config.hosted.apiBaseUrl,
             apiKey: credential.apiKey,
+            workspace: resolveWorkspace(argv, opts.env ?? process.env),
             fetchImpl: opts.fetchImpl,
         });
         await dispatchHosted(argv, client, stdout, stderr, opts.now ?? Date.now);
@@ -148,7 +149,7 @@ async function dispatchHosted(argv, client, stdout, stderr, now) {
     }
     if (args[0] === 'profile') {
         if (args[1] === 'rename' || args[1] === 'use') {
-            throw new ConfigError(`webcmd profile ${args[1]} is not available in hosted mode.`, 'Hosted mode supports: webcmd profile list, create, get, and delete.');
+            throw new ConfigError(`webcmd profile ${args[1]} is not available in hosted mode.`, 'Hosted mode supports: webcmd profile list and delete.');
         }
         const parsed = parseHostedProfileSurface(args.slice(1), normalized.literal);
         if (parsed.kind === 'help') {
@@ -577,7 +578,7 @@ function parseHostedProfileSurface(argv, literal) {
     root.exitOverride().configureOutput(output);
     profile.exitOverride().configureOutput(output);
     const configureFormat = (command) => command.option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table');
-    const setParsed = (command, surface, value, userId) => {
+    const setParsed = (command, surface, value) => {
         const options = surface.opts();
         parsed = {
             kind: 'run',
@@ -585,15 +586,10 @@ function parseHostedProfileSurface(argv, literal) {
             format: options.format,
             formatExplicit: surface.getOptionValueSource('format') === 'cli',
             ...(value !== undefined ? { value } : {}),
-            ...(userId !== undefined ? { userId } : {}),
         };
     };
     const list = configureFormat(profile.command('list'));
     list.exitOverride().configureOutput(output).action(() => setParsed('list', list));
-    const create = configureFormat(profile.command('create').argument('<name>').option('--user-id <id>'));
-    create.exitOverride().configureOutput(output).action((name, options) => setParsed('create', create, name, options.userId));
-    const get = configureFormat(profile.command('get').argument('<profile>'));
-    get.exitOverride().configureOutput(output).action((selector) => setParsed('get', get, selector));
     const remove = configureFormat(profile.command('delete').argument('<profile-id>'));
     remove.exitOverride().configureOutput(output).action((profileId) => setParsed('delete', remove, profileId));
     try {
@@ -612,39 +608,15 @@ function parseHostedProfileSurface(argv, literal) {
     return parsed;
 }
 async function dispatchHostedProfile(parsed, client, stdout) {
-    let result;
-    if (parsed.command === 'list') {
-        result = (await client.listProfiles()).profiles;
-    }
-    else if (parsed.command === 'create') {
-        result = (await client.createProfile({
-            name: parsed.value,
-            ...(parsed.userId !== undefined ? { userId: parsed.userId } : {}),
-        })).profile;
-    }
-    else if (parsed.command === 'get') {
-        result = resolveHostedProfile((await client.listProfiles()).profiles, parsed.value);
-    }
-    else {
-        result = await client.deleteProfile(parsed.value);
-    }
+    const result = parsed.command === 'list'
+        ? (await client.listProfiles()).profiles
+        : await client.deleteProfile(parsed.value);
     await renderOutput(result, {
         fmt: parsed.format,
         fmtExplicit: parsed.formatExplicit,
         stdout,
     });
 }
-function resolveHostedProfile(profiles, selector) {
-    const matches = profiles.filter(profile => profile.id === selector || profile.name === selector || profile.userId === selector);
-    const distinct = [...new Map(matches.map(profile => [profile.id, profile])).values()];
-    if (distinct.length === 0) {
-        throw new CliError('PROFILE_NOT_FOUND', 'Profile was not found.', undefined, EXIT_CODES.EMPTY_RESULT);
-    }
-    if (distinct.length > 1) {
-        throw new CliError('AMBIGUOUS_PROFILE', 'The profile selector matched multiple profiles.', 'Use the immutable profile ID returned by webcmd profile list.', EXIT_CODES.TEMPFAIL);
-    }
-    return distinct[0];
-}
 function parseHostedCompletionSurface(argv, literal) {
     let stdout = '';
     let stderr = '';

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

@@ -226,14 +226,14 @@ describe('runHostedCli', () => {
     const publicProfile = {
         id: 'profile_work',
         name: 'Work',
-        userId: 'user_64256',
+        workspace: 'ws_demo',
         default: false,
         status: 'available',
         createdAt: '2026-07-24T00:00:00.000Z',
         updatedAt: '2026-07-24T00:00:00.000Z',
         lastUsedAt: '2026-07-24T00:00:00.000Z',
     };
-    it('lists, creates, resolves, gets, and deletes hosted profiles without fetching the manifest', async () => {
+    it('lists and deletes hosted profiles without fetching the manifest', async () => {
         const requests = [];
         const fetchImpl = vi.fn(async (url, init) => {
             const request = {
@@ -242,9 +242,6 @@ describe('runHostedCli', () => {
                 ...(init?.body ? { body: JSON.parse(String(init.body)) } : {}),
             };
             requests.push(request);
-            if (request.method === 'POST') {
-                return new Response(JSON.stringify({ ok: true, profile: publicProfile }), { status: 201 });
-            }
             if (request.method === 'DELETE') {
                 return new Response(JSON.stringify({ ok: true, deleted: true }));
             }
@@ -252,10 +249,6 @@ describe('runHostedCli', () => {
         });
         for (const argv of [
             ['profile', 'list', '-f', 'json'],
-            ['profile', 'create', 'Work', '--user-id', 'user_64256', '-f', 'json'],
-            ['profile', 'get', 'Work', '-f', 'json'],
-            ['profile', 'get', 'user_64256', '-f', 'json'],
-            ['profile', 'get', 'profile_work', '-f', 'json'],
             ['profile', 'delete', 'profile_work', '-f', 'json'],
         ]) {
             const stdout = sink();
@@ -271,63 +264,46 @@ describe('runHostedCli', () => {
             expect(stdout.text()).toContain(argv[1] === 'delete' ? '"deleted": true' : '"id": "profile_work"');
         }
         expect(requests).toEqual([
-            { url: 'https://api.example.com/v1/profiles', method: 'GET' },
-            {
-                url: 'https://api.example.com/v1/profiles',
-                method: 'POST',
-                body: { name: 'Work', userId: 'user_64256' },
-            },
-            { url: 'https://api.example.com/v1/profiles', method: 'GET' },
-            { url: 'https://api.example.com/v1/profiles', method: 'GET' },
             { url: 'https://api.example.com/v1/profiles', method: 'GET' },
             { url: 'https://api.example.com/v1/profiles/profile_work', method: 'DELETE' },
         ]);
         expect(requests.some(request => request.url.endsWith('/v1/manifest'))).toBe(false);
     });
-    it('deduplicates universal profile matches and rejects missing or ambiguous selectors', async () => {
+    it.each(['create', 'get'])('rejects the removed profile %s subcommand', async (command) => {
+        const stderr = sink();
+        const fetchImpl = vi.fn();
+        const result = await runHostedCli(['profile', command, 'Work'], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stderr: stderr.stream,
+            fetchImpl,
+        });
+        expect(result.handled).toBe(true);
+        expect(stderr.text()).toMatch(/unknown command|not supported/i);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it('threads the ambient workspace onto hosted profile requests', async () => {
         const cases = [
-            {
-                selector: 'same',
-                profiles: [{ ...publicProfile, id: 'profile_same', name: 'same', userId: 'same' }],
-                exitCode: 0,
-                stdout: '"id": "profile_same"',
-                stderr: '',
-            },
-            {
-                selector: 'missing',
-                profiles: [publicProfile],
-                exitCode: 66,
-                stdout: '',
-                stderr: 'code: PROFILE_NOT_FOUND',
-            },
-            {
-                selector: 'shared',
-                profiles: [
-                    { ...publicProfile, id: 'profile_one', name: 'shared' },
-                    { ...publicProfile, id: 'profile_two', name: 'Other', userId: 'shared' },
-                ],
-                exitCode: 75,
-                stdout: '',
-                stderr: 'code: AMBIGUOUS_PROFILE',
-            },
+            { name: 'from WEBCMD_WORKSPACE env', argv: ['profile', 'list', '-f', 'json'], env: { WEBCMD_WORKSPACE: 'ws1' }, expected: 'ws1' },
+            { name: 'from --workspace flag', argv: ['--workspace', 'ws2', 'profile', 'list', '-f', 'json'], env: {}, expected: 'ws2' },
         ];
         for (const testCase of cases) {
+            let capturedHeader = null;
+            const fetchImpl = vi.fn(async (_url, init) => {
+                capturedHeader = new Headers(init?.headers).get('x-webcmd-workspace');
+                return new Response(JSON.stringify({ ok: true, profiles: [publicProfile] }));
+            });
             const stdout = sink();
             const stderr = sink();
-            const fetchImpl = vi.fn(async () => new Response(JSON.stringify({ ok: true, profiles: testCase.profiles })));
-            const result = await runHostedCli(['profile', 'get', testCase.selector, '-f', 'json'], {
+            const result = await runHostedCli(testCase.argv, {
                 config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
                 stdout: stdout.stream,
                 stderr: stderr.stream,
                 fetchImpl,
+                env: testCase.env,
             });
-            expect(result.exitCode).toBe(testCase.exitCode);
-            expect(stdout.text()).toContain(testCase.stdout);
-            expect(stderr.text()).toContain(testCase.stderr);
-            if (testCase.selector === 'shared') {
-                expect(stderr.text()).toContain('Use the immutable profile ID returned by webcmd profile list.');
-            }
-            expect(fetchImpl).toHaveBeenCalledTimes(1);
+            expect(result).toEqual({ handled: true, exitCode: 0 });
+            expect(stderr.text()).toBe('');
+            expect(capturedHeader).toBe(testCase.expected);
         }
     });
     it.each(['rename', 'use'])('rejects local-only profile %s in hosted mode without an API call', async (command) => {

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

@@ -42,7 +42,7 @@ export interface HostedManifest {
 export interface HostedPublicProfile {
     id: string;
     name: string | null;
-    userId: string | null;
+    workspace: string | null;
     default: boolean;
     status: 'pending' | 'available';
     createdAt: string;
@@ -53,10 +53,6 @@ export interface HostedProfilesResponse {
     ok: true;
     profiles: HostedPublicProfile[];
 }
-export interface HostedProfileResponse {
-    ok: true;
-    profile: HostedPublicProfile;
-}
 export interface HostedExecution {
     id: string;
     command: string;

package/dist/src/manifest-types.d.ts

@@ -42,6 +42,4 @@ export interface ManifestEntry {
     siteSession?: 'ephemeral' | 'persistent';
     /** Fresh page behavior for persistent site sessions — see CliCommand.freshPage */
     freshPage?: boolean;
-    /** Default browser window visibility — see CliCommand.defaultWindowMode */
-    defaultWindowMode?: 'foreground' | 'background';
 }

package/dist/src/registry.d.ts

@@ -75,8 +75,6 @@ interface BaseCliCommand {
      * combining them is a contradiction and fails at registration.
      */
     freshPage?: boolean;
-    /** Default browser window mode for commands whose UX requires visibility. */
-    defaultWindowMode?: 'foreground' | 'background';
     /** Override the default CLI output format when the user does not pass -f/--format. */
     defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
     /** Optional auth-status metadata attached by shared auth adapters. */

package/dist/src/registry.js

@@ -30,7 +30,6 @@ export function cli(opts) {
         navigateBefore: opts.navigateBefore,
         siteSession: opts.siteSession,
         freshPage: opts.freshPage,
-        defaultWindowMode: opts.defaultWindowMode,
         defaultFormat: opts.defaultFormat,
         authStatus: opts.authStatus,
     };

package/dist/src/root-command-surface.js

@@ -35,6 +35,11 @@ export function parseHostedRootCommandSurface(argv) {
     let stderr = '';
     const boundary = findRootCommandBoundary(input);
     const root = configureRootCommandSurface(new Command('webcmd'))
+        // Hosted-only: registered here (not in the shared configureRootCommandSurface)
+        // so the local CLI surface is unaffected. Lets Commander's structural parse
+        // consume `--workspace <id>` before the site/command token instead of
+        // throwing an unknown-option error.
+        .option('--workspace <id>', 'Hosted workspace id/slug for the request')
         .exitOverride()
         .configureOutput({
         writeOut: value => { stdout += value; },
@@ -89,13 +94,16 @@ export function parseHostedRootCommandSurface(argv) {
 function findRootCommandBoundary(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
-        if (token === '--profile') {
+        if (token === '--profile' || token === '--workspace') {
             // Commander requires and consumes the next token even when it is `--` or
             // starts with a dash. Structural failures have already been reported.
+            // `--workspace` is hosted-only (not a registered Commander option here)
+            // but must still be skipped as a value pair so it and its value are not
+            // mistaken for the site/command token and forwarded to the server.
             index += 1;
             continue;
         }
-        if (token.startsWith('--profile='))
+        if (token.startsWith('--profile=') || token.startsWith('--workspace='))
             continue;
         if (token === '--')
             return { separatorIndex: index };