@agentrhq/webcmd 0.3.1 → 0.3.3

package/dist/src/session-lease.test.js

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
+import { SESSION_LEASE_TTL_MS, SessionLeaseRegistry, clearDaemonRunContext, generateRunId, getDaemonRunContext, getSessionLeaseKey, isSessionLeaseCommand, isUnknownOutcomeError, runWithDaemonRunContext, setDaemonRunContext, } from './session-lease.js';
+const T0 = 1_000_000;
+describe('logical daemon run context', () => {
+    afterEach(() => {
+        const current = getDaemonRunContext();
+        if (current)
+            clearDaemonRunContext(current.runId);
+        vi.restoreAllMocks();
+    });
+    it('keeps one run id stable while a logical run is bound and generates a different id for the next run', () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        const firstRunId = generateRunId();
+        setDaemonRunContext({ runId: firstRunId, command: 'chatgpt ask', access: 'write' });
+        expect(getDaemonRunContext()?.runId).toBe(firstRunId);
+        expect(getDaemonRunContext()?.runId).toBe(firstRunId);
+        clearDaemonRunContext(firstRunId);
+        const secondRunId = generateRunId();
+        expect(secondRunId).not.toBe(firstRunId);
+        expect(firstRunId).toMatch(new RegExp(`^run_${process.pid}_1763000000000_\\d+$`));
+    });
+    it('does not let deferred cleanup from an older run clear a newer run context', () => {
+        setDaemonRunContext({ runId: 'run_111_1_1', command: 'chatgpt ask', access: 'write' });
+        setDaemonRunContext({ runId: 'run_222_2_2', command: 'claude ask', access: 'write' });
+        clearDaemonRunContext('run_111_1_1');
+        expect(getDaemonRunContext()).toEqual({
+            runId: 'run_222_2_2',
+            command: 'claude ask',
+            access: 'write',
+        });
+        clearDaemonRunContext('run_222_2_2');
+        expect(getDaemonRunContext()).toBeUndefined();
+    });
+    it('only accepts a concrete run context through the setter', () => {
+        expectTypeOf(setDaemonRunContext).parameter(0).toEqualTypeOf();
+    });
+    it('keeps overlapping async run contexts isolated across awaits', async () => {
+        let resumeFirst;
+        const firstGate = new Promise(resolve => { resumeFirst = resolve; });
+        const firstContext = {
+            runId: 'run_111_1_1',
+            command: 'first write',
+            access: 'write',
+        };
+        const secondContext = {
+            runId: 'run_222_2_2',
+            command: 'second write',
+            access: 'write',
+        };
+        const first = runWithDaemonRunContext(firstContext, async () => {
+            await firstGate;
+            return getDaemonRunContext();
+        });
+        const second = runWithDaemonRunContext(secondContext, async () => getDaemonRunContext());
+        expect(await second).toEqual(secondContext);
+        resumeFirst();
+        expect(await first).toEqual(firstContext);
+        expect(getDaemonRunContext()).toBeUndefined();
+    });
+});
+describe('isUnknownOutcomeError', () => {
+    it('recognizes public, daemon, and message codes case-insensitively', () => {
+        expect(isUnknownOutcomeError({ code: 'COMMAND_RESULT_UNKNOWN' })).toBe(true);
+        expect(isUnknownOutcomeError({ errorCode: 'Command_Lost' })).toBe(true);
+        expect(isUnknownOutcomeError(new Error('daemon returned RESULT_EVICTED'))).toBe(true);
+        expect(isUnknownOutcomeError({ daemonCode: 'attach_failed', message: 'ordinary failure' })).toBe(false);
+    });
+    it('walks causes and AggregateError members without looping on cycles', () => {
+        const cyclic = new Error('outer');
+        cyclic.cause = cyclic;
+        const aggregate = new AggregateError([
+            cyclic,
+            new Error('wrapped', { cause: { errorCode: 'COMMAND_LOST' } }),
+        ]);
+        expect(isUnknownOutcomeError(aggregate)).toBe(true);
+        expect(isUnknownOutcomeError(cyclic)).toBe(false);
+    });
+});
+describe('session lease partitions', () => {
+    it('partitions persistent writes by resolved profile, surface, and encoded site', () => {
+        const workChatgpt = getSessionLeaseKey('work', 'adapter', 'site:chatgpt');
+        expect(workChatgpt).toBe('work␟adapter␟site%3Achatgpt');
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('personal', 'adapter', 'site:chatgpt'));
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('work', 'adapter', 'site:claude'));
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('work', 'browser', 'site:chatgpt'));
+    });
+    it('does not arbitrate reads, ephemeral sessions, raw browser operations, or incomplete identities', () => {
+        const eligible = {
+            surface: 'adapter',
+            siteSession: 'persistent',
+            access: 'write',
+            session: 'site:chatgpt',
+            runId: 'run_111_1_1',
+        };
+        expect(isSessionLeaseCommand(eligible)).toBe(true);
+        expect(isSessionLeaseCommand({ ...eligible, access: 'read' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, siteSession: 'ephemeral' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, surface: 'browser' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, session: '' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, runId: undefined })).toBe(false);
+    });
+});
+describe('SessionLeaseRegistry', () => {
+    const KEY = getSessionLeaseKey('work', 'adapter', 'site:chatgpt');
+    let now = T0;
+    beforeEach(() => {
+        now = T0;
+    });
+    function registry() {
+        return new SessionLeaseRegistry(() => now);
+    }
+    function acquire(registry, runId, key = KEY) {
+        return registry.acquire({ key, runId, command: 'chatgpt ask', pid: Number(runId.split('_')[1]) }, () => false);
+    }
+    it('acquires a free key and returns the live holder on a conflicting run without mutation', () => {
+        const leases = registry();
+        expect(acquire(leases, 'run_111_1_1')).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({
+                key: KEY,
+                runId: 'run_111_1_1',
+                command: 'chatgpt ask',
+                pid: 111,
+                acquiredAt: T0,
+                heartbeatAt: T0,
+            }),
+        });
+        now += 1_000;
+        const conflict = acquire(leases, 'run_222_2_2');
+        expect(conflict).toEqual({
+            acquired: false,
+            holder: expect.objectContaining({ runId: 'run_111_1_1', heartbeatAt: T0 }),
+        });
+        expect(leases.list(() => false)).toEqual([
+            expect.objectContaining({ runId: 'run_111_1_1', heartbeatAt: T0 }),
+        ]);
+    });
+    it('recovers the holder pid from a generated run id when explicit metadata is absent', () => {
+        const leases = registry();
+        expect(leases.acquire({ key: KEY, runId: 'run_4242_1700000000000_7', command: 'chatgpt ask' }, () => false)).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ pid: 4242 }),
+        });
+    });
+    it.each([
+        0,
+        -1,
+        1.5,
+        Number.NaN,
+        Number.POSITIVE_INFINITY,
+        Number.MAX_SAFE_INTEGER + 1,
+    ])('omits a non-actionable explicit holder pid (%s)', (pid) => {
+        const leases = registry();
+        const result = leases.acquire({ key: KEY, runId: 'opaque-run-id', command: 'chatgpt ask', pid }, () => false);
+        expect(result.acquired).toBe(true);
+        if (result.acquired)
+            expect(result.lease).not.toHaveProperty('pid');
+    });
+    it.each([
+        'run_0_1700000000000_1',
+        'run_-1_1700000000000_1',
+        'run_1.5_1700000000000_1',
+        'run_NaN_1700000000000_1',
+        'run_Infinity_1700000000000_1',
+        `run_${Number.MAX_SAFE_INTEGER + 1}_1700000000000_1`,
+    ])('does not recover a non-actionable holder pid from %s', (runId) => {
+        const leases = registry();
+        const result = leases.acquire({ key: KEY, runId, command: 'chatgpt ask' }, () => false);
+        expect(result.acquired).toBe(true);
+        if (result.acquired)
+            expect(result.lease).not.toHaveProperty('pid');
+    });
+    it('treats same-run acquisition and explicit heartbeat as owner-only liveness refreshes', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS;
+        const refreshed = acquire(leases, 'run_111_1_1');
+        expect(refreshed).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ acquiredAt: T0, heartbeatAt: now }),
+        });
+        now += 10;
+        expect(leases.heartbeat(KEY, 'run_999_9_9')).toBe(false);
+        expect(leases.heartbeat(KEY, 'run_111_1_1')).toBe(true);
+        expect(leases.list(() => false)[0]).toMatchObject({ acquiredAt: T0, heartbeatAt: now });
+    });
+    it('lets a challenger acquire after expiry', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS + 1;
+        expect(acquire(leases, 'run_222_2_2')).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ runId: 'run_222_2_2', acquiredAt: now }),
+        });
+    });
+    it('keeps an expired holder live while the holder still has pending work', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS + 10_000;
+        const conflict = leases.acquire({ key: KEY, runId: 'run_222_2_2', command: 'chatgpt ask', pid: 222 }, (runId) => runId === 'run_111_1_1');
+        expect(conflict).toEqual({
+            acquired: false,
+            holder: expect.objectContaining({ runId: 'run_111_1_1' }),
+        });
+        expect(leases.list((runId) => runId === 'run_111_1_1')).toHaveLength(1);
+        expect(leases.list(() => false)).toEqual([]);
+    });
+    it('releases only leases owned by the requested run and reports the count', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        acquire(leases, 'run_111_1_1', getSessionLeaseKey('work', 'adapter', 'site:claude'));
+        expect(leases.releaseByRunId('run_999_9_9')).toBe(0);
+        expect(leases.list(() => false)).toHaveLength(2);
+        expect(leases.releaseByRunId('run_111_1_1')).toBe(2);
+        expect(leases.list(() => false)).toEqual([]);
+    });
+});

package/dist/src/skills.d.ts

@@ -4,7 +4,7 @@ export interface WebcmdSkillInfo {
     version: string;
     path: string;
 }
-export interface WebcmdSkillInstallOptions {
+export interface WebcmdSkillOptions {
     provider?: string;
     scope?: string;
     customPath?: string;
@@ -18,15 +18,19 @@ export interface WebcmdSkillLink {
     stableLink: string;
     destination?: string;
 }
-export interface WebcmdSkillInstallResult {
+export interface WebcmdSkillAddResult {
     provider?: SkillProvider;
     scope?: SkillScope;
     skills: WebcmdSkillLink[];
 }
+export interface WebcmdSkillRemoveResult {
+    removed: string[];
+}
 type SkillProvider = 'agents' | 'codex' | 'claude';
 type SkillScope = 'user' | 'project';
 export declare function getSkillsRoot(packageRoot?: string): string;
 export declare function listWebcmdSkills(packageRoot?: string): WebcmdSkillInfo[];
-export declare function installWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
-export declare function updateWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export declare function addWebcmdSkills(options?: WebcmdSkillOptions): WebcmdSkillAddResult;
+export declare function updateWebcmdSkill(options?: WebcmdSkillOptions): WebcmdSkillAddResult;
+export declare function removeWebcmdSkills(options?: WebcmdSkillOptions): WebcmdSkillRemoveResult;
 export {};

package/dist/src/skills.js

@@ -19,7 +19,7 @@ export function listWebcmdSkills(packageRoot) {
         .filter((entry) => entry !== null)
         .sort((a, b) => a.name.localeCompare(b.name));
 }
-export function installWebcmdSkill(options = {}) {
+export function addWebcmdSkills(options = {}) {
     const provider = options.customPath === undefined ? normalizeProvider(options.provider) : undefined;
     const scope = normalizeScope(options.scope);
     const skills = updateStableSkillLinks(options)
@@ -46,6 +46,35 @@ export function updateWebcmdSkill(options = {}) {
         }),
     };
 }
+export function removeWebcmdSkills(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const cwd = options.cwd ?? process.cwd();
+    const roots = new Set([
+        ...['.agents', '.codex', '.claude'].flatMap((dir) => [
+            path.join(homeDir, dir, 'skills'),
+            path.join(cwd, dir, 'skills'),
+        ]),
+        ...(options.customPath === undefined ? [] : [expandHomePath(options.customPath)]),
+        path.join(homeDir, '.webcmd', 'skills'),
+    ]);
+    const skills = listWebcmdSkills(options.packageRoot);
+    const removed = [];
+    for (const root of roots) {
+        for (const skill of skills) {
+            const linkPath = path.join(root, skill.name);
+            const current = safeLstat(linkPath);
+            if (!current)
+                continue;
+            if (!current.isSymbolicLink()) {
+                throw new ArgumentError(`Refusing to remove non-symlink path: ${linkPath}`, 'Remove it manually if it is no longer needed.');
+            }
+            removed.push(linkPath);
+        }
+    }
+    for (const linkPath of removed)
+        fs.unlinkSync(linkPath);
+    return { removed };
+}
 function updateStableSkillLinks(options) {
     const skillsRoot = getSkillsRoot(options.packageRoot);
     const skills = listWebcmdSkills(options.packageRoot);

package/dist/src/skills.test.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import yaml from 'js-yaml';
 import { describe, expect, it } from 'vitest';
 import { ArgumentError } from './errors.js';
-import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
+import { addWebcmdSkills, listWebcmdSkills, removeWebcmdSkills, updateWebcmdSkill } from './skills.js';
 function makePackageRoot(label = 'current') {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), `webcmd-skills-${label}-`));
     fs.mkdirSync(path.join(root, 'skills', 'webcmd-browser'), { recursive: true });
@@ -80,18 +80,18 @@ describe('webcmd skills content', () => {
             'webcmd-usage',
         ]);
     });
-    it('installs bundled skills once and refreshes them after package updates', () => {
+    it('adds bundled skills once and refreshes them after package updates', () => {
         const firstRoot = makePackageRoot('first');
         const secondRoot = makePackageRoot('second');
         const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
         const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
-        const installed = installWebcmdSkill({ packageRoot: firstRoot, homeDir, cwd, provider: 'codex', scope: 'project' });
-        expect(installed).toMatchObject({
+        const added = addWebcmdSkills({ packageRoot: firstRoot, homeDir, cwd, provider: 'codex', scope: 'project' });
+        expect(added).toMatchObject({
             provider: 'codex',
             scope: 'project',
         });
-        expect(installed.skills.map((skill) => skill.name)).toEqual(['smart-search', 'webcmd-autofix', 'webcmd-browser']);
-        for (const skill of installed.skills) {
+        expect(added.skills.map((skill) => skill.name)).toEqual(['smart-search', 'webcmd-autofix', 'webcmd-browser']);
+        for (const skill of added.skills) {
             expect(skill.source).toBe(path.join(firstRoot, 'skills', skill.name));
             expect(skill.stableLink).toBe(path.join(homeDir, '.webcmd', 'skills', skill.name));
             expect(skill.destination).toBe(path.join(cwd, '.codex', 'skills', skill.name));
@@ -99,22 +99,22 @@ describe('webcmd skills content', () => {
         }
         const updated = updateWebcmdSkill({ packageRoot: secondRoot, homeDir });
         expect(updated.skills.every((skill) => skill.destination === undefined)).toBe(true);
-        for (const skill of installed.skills) {
+        for (const skill of added.skills) {
             expect(real(skill.destination)).toBe(real(path.join(secondRoot, 'skills', skill.name)));
         }
     });
-    it('installs bundled skills into a custom skills directory', () => {
+    it('adds bundled skills into a custom skills directory', () => {
         const packageRoot = makePackageRoot();
         const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
         const customPath = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-custom-skills-'));
-        const installed = installWebcmdSkill({ packageRoot, homeDir, customPath });
-        expect(installed.provider).toBeUndefined();
-        expect(installed.skills.map((skill) => skill.destination)).toEqual([
+        const added = addWebcmdSkills({ packageRoot, homeDir, customPath });
+        expect(added.provider).toBeUndefined();
+        expect(added.skills.map((skill) => skill.destination)).toEqual([
             path.join(customPath, 'smart-search'),
             path.join(customPath, 'webcmd-autofix'),
             path.join(customPath, 'webcmd-browser'),
         ]);
-        for (const skill of installed.skills) {
+        for (const skill of added.skills) {
             expect(real(skill.destination)).toBe(real(skill.source));
         }
     });
@@ -125,4 +125,32 @@ describe('webcmd skills content', () => {
         fs.mkdirSync(stablePath, { recursive: true });
         expect(() => updateWebcmdSkill({ packageRoot, homeDir })).toThrow(ArgumentError);
     });
+    it('removes bundled skill links from every supported location', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
+        const customPath = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-custom-skills-'));
+        for (const provider of ['agents', 'codex', 'claude']) {
+            addWebcmdSkills({ packageRoot, homeDir, cwd, provider, scope: 'user' });
+            addWebcmdSkills({ packageRoot, homeDir, cwd, provider, scope: 'project' });
+        }
+        addWebcmdSkills({ packageRoot, homeDir, cwd, customPath });
+        const result = removeWebcmdSkills({ packageRoot, homeDir, cwd, customPath });
+        expect(result.removed).toHaveLength(24);
+        for (const linkPath of result.removed) {
+            expect(() => fs.lstatSync(linkPath)).toThrow();
+        }
+        expect(removeWebcmdSkills({ packageRoot, homeDir, cwd, customPath })).toEqual({ removed: [] });
+    });
+    it('refuses removal before deleting any links when a destination is not a symlink', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
+        const added = addWebcmdSkills({ packageRoot, homeDir, cwd, provider: 'agents', scope: 'user' });
+        const blocker = path.join(cwd, '.codex', 'skills', 'smart-search');
+        fs.mkdirSync(blocker, { recursive: true });
+        expect(() => removeWebcmdSkills({ packageRoot, homeDir, cwd })).toThrow(ArgumentError);
+        expect(fs.lstatSync(added.skills[0].destination).isSymbolicLink()).toBe(true);
+        expect(fs.lstatSync(blocker).isDirectory()).toBe(true);
+    });
 });

package/hosted-contract.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "webcmdVersion": "0.3.1",
+  "webcmdVersion": "0.3.3",
   "outputFormats": [
     "table",
     "plain",
@@ -26634,7 +26634,7 @@
       "name": "auth",
       "description": "Authenticate with Spotify (OAuth — run once)",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [],
       "options": [],
@@ -26644,9 +26644,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26655,7 +26656,7 @@
       "name": "next",
       "description": "Skip to next track",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [],
       "options": [],
@@ -26665,9 +26666,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26676,7 +26678,7 @@
       "name": "pause",
       "description": "Pause playback",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [],
       "options": [],
@@ -26686,9 +26688,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26697,7 +26700,7 @@
       "name": "play",
       "description": "Resume playback or search and play a track/artist",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26719,9 +26722,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26730,7 +26734,7 @@
       "name": "prev",
       "description": "Skip to previous track",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [],
       "options": [],
@@ -26740,9 +26744,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26751,7 +26756,7 @@
       "name": "queue",
       "description": "Add a track to the playback queue",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26772,9 +26777,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26783,7 +26789,7 @@
       "name": "repeat",
       "description": "Set repeat mode (off / track / context)",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26808,9 +26814,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26819,7 +26826,7 @@
       "name": "search",
       "description": "Search for tracks",
       "access": "read",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26851,9 +26858,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26862,7 +26870,7 @@
       "name": "shuffle",
       "description": "Toggle shuffle on/off",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26886,9 +26894,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26897,7 +26906,7 @@
       "name": "status",
       "description": "Show current playback status",
       "access": "read",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [],
       "options": [],
@@ -26911,9 +26920,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {
@@ -26922,7 +26932,7 @@
       "name": "volume",
       "description": "Set playback volume (0-100)",
       "access": "write",
-      "strategy": "PUBLIC",
+      "strategy": "LOCAL",
       "browser": false,
       "positionals": [
         {
@@ -26942,9 +26952,10 @@
       "aliases": [],
       "defaultFormat": "table",
       "fileArguments": [],
-      "sessionPolicy": "create-or-reuse",
+      "sessionPolicy": "local-only",
       "availability": {
-        "mode": "hosted"
+        "mode": "local-only",
+        "reason": "local-tool"
       }
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -77,6 +77,7 @@
   ],
   "author": "AgentR",
   "license": "Apache-2.0",
+  "homepage": "https://docs.webcmd.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agentrhq/webcmd.git"
@@ -112,4 +113,4 @@
   "overrides": {
     "postcss": "^8.5.10"
   }
-}
+}