@agentrhq/webcmd 0.3.2 → 0.3.4

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

@@ -1,5 +1,5 @@
-import { dispatchCloakAction } from './actions.js';
-import { CloakSessionManager } from './session-manager.js';
+import { dispatchCloakAction, resolveCloakCommandProfileId } from './actions.js';
+import { CloakSessionManager, resolveCloakBrowserVersion } from './session-manager.js';
 export class LocalCloakRuntimeProvider {
     opts;
     manager;
@@ -12,12 +12,15 @@ export class LocalCloakRuntimeProvider {
         return {
             runtimeConnected: true,
             runtimeName: 'cloak',
-            runtimeVersion: undefined,
+            runtimeVersion: resolveCloakBrowserVersion(),
             profiles,
             pending: 0,
             commandResultUnknown: 0,
         };
     }
+    resolveProfileId(command) {
+        return resolveCloakCommandProfileId(this.manager, command);
+    }
     async dispatch(command) {
         return dispatchCloakAction(this.manager, command);
     }

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

@@ -27,6 +27,7 @@ function fakePage(url) {
 function makeProviderWithFakePage() {
     const pages = [fakePage('https://example.com/')];
     const context = {
+        on: vi.fn(),
         pages: vi.fn(() => pages.filter((page) => !page.isClosed())),
         newPage: vi.fn(async () => {
             const page = fakePage('about:blank');

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

@@ -3,6 +3,8 @@ import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbr
 import type { BrowserSurface, BrowserWindowMode, SiteSessionMode } from '../../protocol.js';
 import { activateDarwinBackgroundContext } from './darwin-background-launch.js';
 import { CloakNetworkCapture } from './network.js';
+/** Installed `cloakbrowser` npm package version, for doctor/status display. */
+export declare function resolveCloakBrowserVersion(): string | undefined;
 export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
 export type RecoverLockedProfile = (userDataDir: string) => Promise<boolean>;
 export interface SessionKeyInput {
@@ -85,6 +87,9 @@ export declare class CloakSessionManager {
     shutdown(): Promise<void>;
     private getProfileRuntime;
     private launchProfileRuntime;
+    private invalidateProfileRuntime;
+    private attachRuntimeLifecycle;
+    private createPageWithRecovery;
     private openEntries;
     private findEntryByPageId;
     private refreshIdleTimer;

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

@@ -1,9 +1,23 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
 import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
 import { activateDarwinBackgroundContext, launchDarwinBackgroundPersistentContext } from './darwin-background-launch.js';
 import { normalizeProfileId, resolveCloakProfileDir } from './profiles.js';
 import { CloakNetworkCapture } from './network.js';
+import { findPackageRoot } from '../../../package-paths.js';
+/** Installed `cloakbrowser` npm package version, for doctor/status display. */
+export function resolveCloakBrowserVersion() {
+    try {
+        const entryPath = fileURLToPath(import.meta.resolve('cloakbrowser'));
+        const pkg = JSON.parse(fs.readFileSync(path.join(findPackageRoot(entryPath), 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 let pageCounter = 0;
 export function resolveLeaseKey(input) {
     const surface = input.surface === 'adapter' ? 'adapter' : 'browser';
@@ -15,6 +29,10 @@ export function resolveLeaseKey(input) {
 function pageIsClosed(page) {
     return page.isClosed?.() === true;
 }
+function isClosedContextError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /Target page, context or browser has been closed/i.test(message);
+}
 export class CloakSessionManager {
     opts;
     networkCapture = new CloakNetworkCapture();
@@ -37,7 +55,7 @@ export class CloakSessionManager {
         return [...this.profiles.entries()].map(([contextId, runtime]) => ({
             contextId,
             runtimeConnected: true,
-            runtimeVersion: runtime.runtimeVersion,
+            runtimeVersion: resolveCloakBrowserVersion(),
             pending: 0,
             lastSeenAt: runtime.lastSeenAt,
         }));
@@ -67,16 +85,21 @@ export class CloakSessionManager {
             if (!pageIsClosed(existing.page))
                 await existing.page.close().catch(() => { });
         }
-        const existingPages = runtime.context.pages();
-        // freshPage must never adopt a leftover tab — its whole point is a clean DOM.
-        const page = !freshPage && existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
-        const pageId = nextPageId();
-        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
-        runtime.pages.set(leaseKey, entry);
-        this.refreshIdleTimer(runtime, leaseKey, entry);
-        runtime.selectedPageId = pageId;
-        runtime.lastSeenAt = Date.now();
-        return { profileId, leaseKey, context: runtime.context, page, pageId };
+        return this.createPageWithRecovery(profileId, input.windowMode, (candidate) => {
+            const existingPages = candidate.context.pages();
+            // freshPage must never adopt a leftover tab — its whole point is a clean DOM.
+            return !freshPage && existingPages[0] && candidate.pages.size === 0
+                ? existingPages[0]
+                : candidate.context.newPage();
+        }, (candidate, page) => {
+            const pageId = nextPageId();
+            const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
+            candidate.pages.set(leaseKey, entry);
+            this.refreshIdleTimer(candidate, leaseKey, entry);
+            candidate.selectedPageId = pageId;
+            candidate.lastSeenAt = Date.now();
+            return { profileId, leaseKey, context: candidate.context, page, pageId };
+        });
     }
     findPageById(pageId, opts = {}) {
         for (const [profileId, runtime] of this.profiles.entries()) {
@@ -137,18 +160,36 @@ export class CloakSessionManager {
         const profileId = normalizeProfileId(input.profileId);
         const session = requireSession(input.session);
         const surface = normalizeSurface(input.surface);
-        const runtime = await this.getProfileRuntime(profileId, input.windowMode);
-        const page = await runtime.context.newPage();
+        const acquired = await this.createPageWithRecovery(profileId, input.windowMode, (candidate) => candidate.context.newPage(), (runtime, page) => ({ runtime, page }));
         if (input.url) {
-            await page.goto(input.url, { waitUntil: 'load' });
+            try {
+                await acquired.page.goto(input.url, { waitUntil: 'load' });
+            }
+            catch (error) {
+                if (!pageIsClosed(acquired.page))
+                    await acquired.page.close().catch(() => { });
+                throw error;
+            }
+        }
+        if (this.profiles.get(profileId) !== acquired.runtime) {
+            if (!pageIsClosed(acquired.page))
+                await acquired.page.close().catch(() => { });
+            throw new Error('Target page, context or browser has been closed');
         }
         const pageId = nextPageId();
         const leaseKey = `${resolveLeaseKey(input)}\u0000${pageId}`;
-        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
-        runtime.pages.set(leaseKey, entry);
-        this.refreshIdleTimer(runtime, leaseKey, entry);
-        runtime.lastSeenAt = Date.now();
-        return { profileId, leaseKey, context: runtime.context, page, pageId };
+        const entry = {
+            page: acquired.page,
+            pageId,
+            session,
+            surface,
+            siteSession: input.siteSession,
+            idleTimeout: input.idleTimeout,
+        };
+        acquired.runtime.pages.set(leaseKey, entry);
+        this.refreshIdleTimer(acquired.runtime, leaseKey, entry);
+        acquired.runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey, context: acquired.runtime.context, page: acquired.page, pageId };
     }
     async selectPage(input) {
         const profileId = normalizeProfileId(input.profileId);
@@ -285,9 +326,44 @@ export class CloakSessionManager {
             context = await launchPersistentContext(launchOptions);
         }
         const runtime = { context, pages: new Map(), lastSeenAt: Date.now() };
+        this.attachRuntimeLifecycle(profileId, runtime);
         this.profiles.set(profileId, runtime);
         return runtime;
     }
+    invalidateProfileRuntime(profileId, runtime) {
+        if (this.profiles.get(profileId) !== runtime)
+            return;
+        this.profiles.delete(profileId);
+        for (const entry of runtime.pages.values()) {
+            if (entry.idleTimer)
+                clearTimeout(entry.idleTimer);
+            this.networkCapture.stop(entry.page);
+        }
+        runtime.pages.clear();
+        runtime.selectedPageId = undefined;
+    }
+    attachRuntimeLifecycle(profileId, runtime) {
+        runtime.context.on('close', () => this.invalidateProfileRuntime(profileId, runtime));
+    }
+    async createPageWithRecovery(profileId, windowMode, createPage, commitPage, attempt = 0) {
+        const runtime = await this.getProfileRuntime(profileId, windowMode);
+        let page;
+        try {
+            page = await createPage(runtime);
+        }
+        catch (error) {
+            if (attempt !== 0 || !isClosedContextError(error))
+                throw error;
+            this.invalidateProfileRuntime(profileId, runtime);
+            return this.createPageWithRecovery(profileId, windowMode, createPage, commitPage, 1);
+        }
+        if (this.profiles.get(profileId) !== runtime) {
+            if (!pageIsClosed(page))
+                await page.close().catch(() => { });
+            throw new Error('Target page, context or browser has been closed');
+        }
+        return commitPage(runtime, page);
+    }
     openEntries(runtime) {
         return [...runtime.pages.entries()].filter(([, entry]) => !pageIsClosed(entry.page));
     }

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { CloakSessionManager } from './session-manager.js';
 import { dispatchCloakAction } from './actions.js';
 function fakeContext() {
+    const listeners = new Map();
     const page = {
         goto: vi.fn().mockResolvedValue(undefined),
         evaluate: vi.fn().mockResolvedValue('ok'),
@@ -14,6 +15,15 @@ function fakeContext() {
     };
     return {
         context: {
+            on(event, listener) {
+                const bucket = listeners.get(event) ?? new Set();
+                bucket.add(listener);
+                listeners.set(event, bucket);
+            },
+            emit(event) {
+                for (const listener of listeners.get(event) ?? [])
+                    listener();
+            },
             pages: vi.fn().mockReturnValue([page]),
             newPage: vi.fn().mockResolvedValue(page),
             cookies: vi.fn().mockResolvedValue([{ name: 'sid', value: '1', domain: 'example.com', path: '/' }]),
@@ -98,6 +108,229 @@ describe('CloakSessionManager', () => {
         expect(second.context).toBe(launched.context);
         expect(first.page).toBe(second.page);
     });
+    it('evicts a closed runtime and clears every tracked page resource', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        const secondPage = fakeContext().page;
+        launched.context.newPage.mockResolvedValue(secondPage);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const stopCapture = vi.spyOn(manager.networkCapture, 'stop');
+        const first = await manager.getPage({ profileId: 'default', session: 'one', surface: 'browser', idleTimeout: 25 });
+        const second = await manager.newPage({ profileId: 'default', session: 'two', surface: 'browser', idleTimeout: 25 });
+        expect(manager.activeProfileIds()).toEqual(['default']);
+        expect(vi.getTimerCount()).toBe(2);
+        launched.context.emit('close');
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(manager.profileStatuses()).toEqual([]);
+        expect(vi.getTimerCount()).toBe(0);
+        expect(stopCapture).toHaveBeenCalledTimes(2);
+        expect(stopCapture).toHaveBeenCalledWith(first.page);
+        expect(stopCapture).toHaveBeenCalledWith(second.page);
+        await vi.advanceTimersByTimeAsync(25);
+        expect(first.page.close).not.toHaveBeenCalled();
+        expect(second.page.close).not.toHaveBeenCalled();
+    });
+    it('does not let a late close from an old runtime evict its replacement', async () => {
+        const first = fakeContext();
+        const replacement = fakeContext();
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser' });
+        first.context.emit('close');
+        const replacementLease = await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' });
+        first.context.emit('close');
+        expect(manager.activeProfileIds()).toEqual(['default']);
+        expect(manager.profileStatuses()).toHaveLength(1);
+        expect((await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' })).context)
+            .toBe(replacementLease.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('coalesces simultaneous replacement launches after a context closes', async () => {
+        const first = fakeContext();
+        const replacement = fakeContext();
+        let resolveReplacement;
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockImplementationOnce(() => new Promise((resolve) => {
+            resolveReplacement = resolve;
+        }));
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser' });
+        first.context.emit('close');
+        const one = manager.getPage({ profileId: 'default', session: 'one', surface: 'browser' });
+        const two = manager.getPage({ profileId: 'default', session: 'two', surface: 'browser' });
+        await Promise.resolve();
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+        resolveReplacement(replacement.context);
+        const leases = await Promise.all([one, two]);
+        expect(leases[0].context).toBe(replacement.context);
+        expect(leases[1].context).toBe(replacement.context);
+    });
+    it('discards a page created after its runtime closes and defers recovery to the next command', async () => {
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        let resolveFirstPage;
+        let markPageCreationStarted;
+        const pageCreationStarted = new Promise((resolve) => {
+            markPageCreationStarted = resolve;
+        });
+        first.context.newPage.mockImplementation(() => {
+            markPageCreationStarted();
+            return new Promise((resolve) => {
+                resolveFirstPage = resolve;
+            });
+        });
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const pendingLease = manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        await pageCreationStarted;
+        first.context.emit('close');
+        resolveFirstPage(first.page);
+        await expect(pendingLease).rejects.toThrow('Target page, context or browser has been closed');
+        expect(first.page.close).toHaveBeenCalled();
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        const lease = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('does not publish an orphaned page after acquisition validation', async () => {
+        vi.useFakeTimers();
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        first.context.newPage.mockImplementation(() => ({
+            then(resolve) {
+                resolve(first.page);
+                queueMicrotask(() => first.context.emit('close'));
+            },
+        }));
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser', idleTimeout: 25 });
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(vi.getTimerCount()).toBe(0);
+        const lease = await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('retries getPage page creation once after a closed-context failure', async () => {
+        const closed = new Error('Target page, context or browser has been closed');
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        first.context.newPage.mockRejectedValue(closed);
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const lease = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('retries explicit newPage page creation once after a closed-context failure', async () => {
+        const closed = new Error('browserContext.newPage: Target page, context or browser has been closed');
+        const first = fakeContext();
+        first.context.newPage.mockRejectedValue(closed);
+        const replacement = fakeContext();
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const lease = await manager.newPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('returns the second closed-context page creation failure without looping', async () => {
+        const firstFailure = new Error('Target page, context or browser has been closed');
+        const secondFailure = new Error('Target page, context or browser has been closed again');
+        const first = fakeContext();
+        first.context.newPage.mockRejectedValue(firstFailure);
+        const replacement = fakeContext();
+        replacement.context.newPage.mockRejectedValue(secondFailure);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await expect(manager.newPage({ profileId: 'default', session: 'work', surface: 'browser' }))
+            .rejects.toBe(secondFailure);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('keeps an explicitly navigated page untracked until navigation succeeds', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        let resolveNavigation;
+        let markNavigationStarted;
+        const navigationStarted = new Promise((resolve) => {
+            markNavigationStarted = resolve;
+        });
+        launched.page.goto.mockImplementation(() => {
+            markNavigationStarted();
+            return new Promise((resolve) => {
+                resolveNavigation = resolve;
+            });
+        });
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const pendingLease = manager.newPage({
+            profileId: 'default',
+            session: 'work',
+            surface: 'browser',
+            idleTimeout: 25,
+            url: 'https://example.com/',
+        });
+        await navigationStarted;
+        const pagesDuringNavigation = await manager.listPages({ profileId: 'default' });
+        const pageIdDuringNavigation = manager.pageIdFor(launched.page);
+        const timersDuringNavigation = vi.getTimerCount();
+        resolveNavigation();
+        const lease = await pendingLease;
+        expect(pagesDuringNavigation).toEqual([]);
+        expect(pageIdDuringNavigation).toBeUndefined();
+        expect(timersDuringNavigation).toBe(0);
+        expect(manager.pageIdFor(launched.page)).toBe(lease.pageId);
+        expect(await manager.listPages({ profileId: 'default' })).toHaveLength(1);
+        expect(vi.getTimerCount()).toBe(1);
+    });
+    it('does not retry or retain a page when navigation fails after creation', async () => {
+        const navigationFailure = new Error('Target page, context or browser has been closed');
+        const launched = fakeContext();
+        launched.page.goto.mockRejectedValue(navigationFailure);
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await expect(manager.newPage({
+            profileId: 'default',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+        })).rejects.toBe(navigationFailure);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        expect(launched.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launched.page.goto).toHaveBeenCalledTimes(1);
+        expect(launched.page.close).toHaveBeenCalledTimes(1);
+        expect(await manager.listPages({ profileId: 'default' })).toEqual([]);
+    });
     it('clears a stale Cloak profile owner and retries when Chromium reports an existing session', async () => {
         const launched = fakeContext();
         const launchPersistentContext = vi.fn()
@@ -125,6 +358,7 @@ describe('CloakSessionManager', () => {
         });
         const openPages = [];
         const context = {
+            on: vi.fn(),
             pages: vi.fn(() => openPages),
             newPage: vi.fn(async () => {
                 const page = makePage();
@@ -159,6 +393,7 @@ describe('CloakSessionManager', () => {
             close: vi.fn().mockResolvedValue(undefined),
         };
         const context = {
+            on: vi.fn(),
             pages: vi.fn().mockReturnValue([leftover]),
             newPage: vi.fn().mockResolvedValue(created),
             cookies: vi.fn().mockResolvedValue([]),

package/dist/src/browser/runtime/provider.d.ts

@@ -4,6 +4,7 @@ export interface RuntimeStatusOptions {
 }
 export interface BrowserRuntimeProvider {
     status(opts?: RuntimeStatusOptions): Promise<BrowserRuntimeStatus>;
+    resolveProfileId?(command: BrowserRuntimeCommand): string;
     dispatch(command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;
     shutdown(): Promise<void>;
 }

package/dist/src/cli.js

@@ -18,7 +18,7 @@ import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
-import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
+import { addWebcmdSkills, listWebcmdSkills, removeWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { buildRootHelpPresentation, classifyAdapter, installCommanderNamespaceStructuredHelp, installRootPresentationHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
@@ -62,15 +62,15 @@ function parseDurationMs(raw, flagName) {
 function timestampFromRaw(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
 }
-function isInteractiveInstall(opts) {
+function isInteractiveSkillAdd(opts) {
     return !opts.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
-async function resolveSkillInstallOptions(opts) {
-    if (!isInteractiveInstall(opts))
+async function resolveSkillAddOptions(opts) {
+    if (!isInteractiveSkillAdd(opts))
         return opts;
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd install skills?', [
+        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd add skills?', [
             { key: '1', label: 'Global', value: 'user', aliases: ['global', 'user', 'g'] },
             { key: '2', label: 'Local project', value: 'project', aliases: ['local', 'project', 'l'] },
         ], '1');
@@ -126,6 +126,24 @@ async function handleSkillLinkCommand(action, json, verb) {
         process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
     }
 }
+function handleSkillRemoveCommand(customPath, json) {
+    try {
+        const result = removeWebcmdSkills({ customPath });
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Webcmd skill links removed: ${result.removed.length}`);
+        for (const linkPath of result.removed)
+            console.log(linkPath);
+    }
+    catch (err) {
+        console.error(`Error: ${getErrorMessage(err)}`);
+        if (err instanceof CliError && err.hint)
+            console.error(`Hint: ${err.hint}`);
+        process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
+    }
+}
 function toIsoTimestamp(timestamp) {
     if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0)
         return undefined;
@@ -706,7 +724,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const skillsCmd = program
         .command('skills')
-        .description('List, install, and update bundled Webcmd skills')
+        .description('List, add, update, and remove bundled Webcmd skills')
         .action(() => {
         const rows = listWebcmdSkills();
         renderOutput(rows, {
@@ -732,24 +750,24 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         });
     });
     skillsCmd
-        .command('install')
-        .description('Install bundled Webcmd skills into an agent skills folder')
+        .command('add')
+        .description('Add bundled Webcmd skills to an agent skills folder')
         .option('-p, --provider <provider>', 'Agent provider: agents, codex, claude')
-        .option('-s, --scope <scope>', 'Install scope: user/global or project/local')
+        .option('-s, --scope <scope>', 'Add scope: user/global or project/local')
         .option('--path <path>', 'Custom agent skills directory')
         .option('--json', 'Output a JSON envelope', false)
         .action(async (opts) => {
         await handleSkillLinkCommand(async () => {
-            const resolved = await resolveSkillInstallOptions(opts);
+            const resolved = await resolveSkillAddOptions(opts);
             if (resolved.provider === 'custom' && !resolved.path) {
                 throw new ArgumentError('Custom skill provider requires --path.', 'Pass --path <skills-dir> or run interactively.');
             }
-            return installWebcmdSkill({
+            return addWebcmdSkills({
                 provider: resolved.provider,
                 scope: resolved.scope,
                 customPath: resolved.path,
             });
-        }, opts.json, 'installed');
+        }, opts.json, 'added');
     });
     skillsCmd
         .command('update')
@@ -765,6 +783,12 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             customPath: opts.path,
         }), opts.json, 'updated');
     });
+    skillsCmd
+        .command('remove')
+        .description('Remove bundled Webcmd skill symlinks from supported locations')
+        .option('--path <path>', 'Also remove links from a custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action((opts) => handleSkillRemoveCommand(opts.path, opts.json));
     const authCmd = registerAuthCommands(program);
     program
         .command('convention-audit')

package/dist/src/cli.test.js

@@ -60,6 +60,11 @@ describe('createProgram root help descriptions', () => {
         expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop');
         expect(descriptionFor(program, 'external')).toBe('install, list, register');
     });
+    it('exposes add and remove without an install command', () => {
+        const skills = createProgram('', '').commands.find((command) => command.name() === 'skills');
+        expect(skills.commands.map((command) => command.name())).toEqual(['list', 'add', 'update', 'remove']);
+        expect(skills.commands.find((command) => command.name() === 'add')?.aliases()).toEqual([]);
+    });
     it('renders auth namespace structured help', () => {
         const argv = process.argv;
         try {