@agentrhq/webcmd 0.3.1 → 0.3.3

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

@@ -103,6 +103,68 @@ describe('HostedClient', () => {
         });
         expect(requests).toEqual([{ url: 'https://api.example.com/v1/manifest', authorization: 'Bearer wcmd_live_test' }]);
     });
+    it('accepts boolean freshPage command metadata', async () => {
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            fetchImpl: async () => new Response(JSON.stringify({
+                ok: true,
+                manifest: {
+                    userId: 'user_demo',
+                    metadata: {
+                        contractSchemaVersion: 1,
+                        webcmdPackageVersion: '0.3.0',
+                        generatedAt: 'now',
+                    },
+                    commands: [{
+                            site: 'district',
+                            name: 'checkout',
+                            command: 'district/checkout',
+                            description: 'Checkout',
+                            access: 'write',
+                            strategy: 'UI',
+                            browser: true,
+                            args: [],
+                            columns: [],
+                            freshPage: true,
+                        }],
+                },
+            }), { status: 200 }),
+        });
+        await expect(client.getManifest()).resolves.toMatchObject({
+            commands: [expect.objectContaining({ freshPage: true })],
+        });
+    });
+    it('rejects non-boolean freshPage command metadata', async () => {
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            fetchImpl: async () => new Response(JSON.stringify({
+                ok: true,
+                manifest: {
+                    userId: 'user_demo',
+                    metadata: {
+                        contractSchemaVersion: 1,
+                        webcmdPackageVersion: '0.3.0',
+                        generatedAt: 'now',
+                    },
+                    commands: [{
+                            site: 'district',
+                            name: 'checkout',
+                            command: 'district/checkout',
+                            description: 'Checkout',
+                            access: 'write',
+                            strategy: 'UI',
+                            browser: true,
+                            args: [],
+                            columns: [],
+                            freshPage: 'yes',
+                        }],
+                },
+            }), { status: 200 }),
+        });
+        await expect(client.getManifest()).rejects.toMatchObject({ code: 'HOSTED_PROTOCOL' });
+    });
     it('parses hosted profile rows without provider identifiers', async () => {
         const client = new HostedClient({
             apiBaseUrl: 'https://api.example.com',

package/dist/src/hosted/main-lifecycle.test.js

@@ -24,6 +24,18 @@ const command = {
     columns: ['value'],
     defaultFormat: 'plain',
 };
+const authCommand = {
+    site: 'auth',
+    name: 'status',
+    command: 'auth/status',
+    description: 'Show hosted login status',
+    access: 'read',
+    strategy: 'PUBLIC',
+    browser: false,
+    args: [],
+    columns: ['value'],
+    defaultFormat: 'plain',
+};
 afterEach(async () => {
     await Promise.all(servers.splice(0).map(server => new Promise((resolve, reject) => {
         server.close(error => error ? reject(error) : resolve());
@@ -77,6 +89,44 @@ describe('hosted CLI process lifecycle', () => {
         expect(result.stdout).toContain('Local-only commands:');
         await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
     }, 20_000);
+    it('runs skills add locally without contacting Cloud when hosted mode is configured', async () => {
+        const fixture = await createHostedFixture('success');
+        const installDir = path.join(fixture.root, 'agent-skills');
+        const result = await runCli(['skills', 'add', '--path', installDir, '--json'], fixture.env);
+        expect(result.status).toBe(0);
+        expect(result.stderr).toBe('');
+        const body = JSON.parse(result.stdout);
+        expect(body.skills.map(skill => skill.name)).toEqual([
+            'smart-search',
+            'webcmd-adapter-author',
+            'webcmd-autofix',
+            'webcmd-browser',
+            'webcmd-browser-sitemap',
+            'webcmd-sitemap-author',
+            'webcmd-usage',
+        ]);
+        expect(body.skills.every(skill => skill.destination?.startsWith(installDir))).toBe(true);
+        await expect(readFile(path.join(installDir, 'webcmd-usage', 'SKILL.md'), 'utf8'))
+            .resolves.toContain('webcmd-usage');
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+        expect(fixture.requests).toEqual([]);
+    }, 20_000);
+    it('keeps hosted auth on Cloud without local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['auth', 'status', '-f', 'plain'], fixture.env);
+        expect(result.stderr).toBe('');
+        expect(result.status).toBe(0);
+        expect(fixture.requests).toEqual(['GET /v1/manifest', 'POST /v1/execute']);
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+    it('rejects daemon commands in hosted mode without local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['daemon', 'status'], fixture.env);
+        expect(result.status).toBe(78);
+        expect(result.stderr).toContain('Hosted mode has no local daemon.');
+        expect(fixture.requests).toEqual([]);
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
 });
 async function createHostedFixture(outcome) {
     const root = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-lifecycle-'));
@@ -84,6 +134,7 @@ async function createHostedFixture(outcome) {
     const configDir = path.join(root, 'config');
     const userClis = path.join(root, '.webcmd', 'clis', 'lifecycle-sentinel');
     const discoverySentinel = path.join(root, 'local-discovery-ran');
+    const requests = [];
     await mkdir(configDir, { recursive: true });
     await mkdir(userClis, { recursive: true });
     await writeFile(path.join(userClis, 'sentinel.js'), [
@@ -92,7 +143,8 @@ async function createHostedFixture(outcome) {
         "export const sentinel = 'cli(';",
         '',
     ].join('\n'));
-    const server = createServer((request, response) => {
+    const server = createServer(async (request, response) => {
+        requests.push(`${request.method ?? 'GET'} ${request.url ?? '/'}`);
         if (request.url === '/v1/manifest') {
             sendChunkedJson(response, {
                 ok: true,
@@ -103,12 +155,16 @@ async function createHostedFixture(outcome) {
                         webcmdPackageVersion: '0.3.0',
                         generatedAt: '2026-07-14T00:00:00.000Z',
                     },
-                    commands: [command],
+                    commands: [command, authCommand],
                 },
             });
             return;
         }
         if (request.url === '/v1/execute' && request.method === 'POST') {
+            let requestBody = '';
+            for await (const chunk of request)
+                requestBody += chunk;
+            const invocation = JSON.parse(requestBody);
             if (outcome === 'failure') {
                 sendChunkedJson(response, {
                     ok: false,
@@ -118,7 +174,7 @@ async function createHostedFixture(outcome) {
                         help: 'Retry the lifecycle fixture.',
                         exitCode: 69,
                     },
-                    execution: { id: 'exec_lifecycle', command: command.command, status: 'failed' },
+                    execution: { id: 'exec_lifecycle', command: invocation.command, status: 'failed' },
                 }, 422);
                 return;
             }
@@ -126,8 +182,10 @@ async function createHostedFixture(outcome) {
                 ok: true,
                 result: { value: largeOutput },
                 columns: ['value'],
-                execution: { id: 'exec_lifecycle', command: command.command, status: 'succeeded' },
-                trace: { executionId: 'exec_lifecycle', receipt: traceReceipt },
+                execution: { id: 'exec_lifecycle', command: invocation.command, status: 'succeeded' },
+                ...(invocation.trace === 'on'
+                    ? { trace: { executionId: 'exec_lifecycle', receipt: traceReceipt } }
+                    : {}),
             });
             return;
         }
@@ -156,10 +214,13 @@ async function createHostedFixture(outcome) {
         updatedAt: '2026-07-14T00:00:00.000Z',
     })}\n`, { mode: 0o600 });
     return {
+        root,
         discoverySentinel,
+        requests,
         env: {
             ...process.env,
             HOME: root,
+            USERPROFILE: root,
             WEBCMD_CONFIG_DIR: configDir,
             WEBCMD_NO_UPDATE_CHECK: '1',
         },

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

@@ -28,6 +28,7 @@ export interface HostedCommand extends CommandSurfaceMetadata {
     columns: string[];
     domain?: string | null;
     defaultFormat?: string | null;
+    freshPage?: boolean;
 }
 export interface HostedManifest {
     userId: string;

package/dist/src/main.js

@@ -65,6 +65,10 @@ if (!fastPathHandled) {
         const { runHostedSetup } = await import('./hosted/setup.js');
         process.exitCode = await runHostedSetup();
     }
+    else if (argv[0] === 'skills') {
+        const { createProgram } = await import('./cli.js');
+        await createProgram(BUILTIN_CLIS, USER_CLIS).parseAsync(argv, { from: 'user' });
+    }
     else {
         const { shouldUseHostedMode } = await import('./hosted/config.js');
         if (shouldUseHostedMode()) {

package/dist/src/package-bin-process.d.ts

@@ -0,0 +1,13 @@
+type SpawnOutput = string | Buffer | null | undefined;
+export interface PackageBinSpawnFailure {
+    error?: Error;
+    signal?: NodeJS.Signals | null;
+    status: number | null;
+    stdout?: SpawnOutput;
+    stderr?: SpawnOutput;
+}
+export declare function packageBinSpawnOptions(platform: NodeJS.Platform, command: string): {
+    shell?: true;
+};
+export declare function formatPackageBinSpawnFailure(command: string, args: string[], result: PackageBinSpawnFailure): string;
+export {};

package/dist/src/package-bin-process.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+export function packageBinSpawnOptions(platform, command) {
+    if (platform !== 'win32')
+        return {};
+    const basename = path.win32.basename(command).toLowerCase();
+    return basename === 'npm' || basename.endsWith('.cmd') ? { shell: true } : {};
+}
+function outputText(output) {
+    return output == null ? '' : output.toString().trim();
+}
+export function formatPackageBinSpawnFailure(command, args, result) {
+    const invocation = [command, ...args].join(' ');
+    if (result.error) {
+        return `${invocation} failed to start: ${result.error.message}`;
+    }
+    const outcome = result.status === null
+        ? `terminated by ${result.signal ?? 'an unknown signal'}`
+        : `exited ${result.status}`;
+    return [
+        `${invocation} ${outcome}`,
+        outputText(result.stdout),
+        outputText(result.stderr),
+    ].filter(Boolean).join('\n');
+}

package/dist/src/package-bin-process.test.d.ts

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

package/dist/src/package-bin-process.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { formatPackageBinSpawnFailure, packageBinSpawnOptions, } from './package-bin-process.js';
+describe('package bin process options', () => {
+    it('uses a shell for npm and cmd shims on Windows', () => {
+        expect(packageBinSpawnOptions('win32', 'npm')).toEqual({ shell: true });
+        expect(packageBinSpawnOptions('win32', 'C:\\prefix\\webcmd.cmd')).toEqual({ shell: true });
+    });
+    it('keeps native executables shell-free', () => {
+        expect(packageBinSpawnOptions('linux', 'npm')).toEqual({});
+        expect(packageBinSpawnOptions('darwin', '/tmp/webcmd')).toEqual({});
+        expect(packageBinSpawnOptions('win32', 'node.exe')).toEqual({});
+    });
+    it('reports launch errors without assuming output streams exist', () => {
+        const error = Object.assign(new Error('spawnSync npm EINVAL'), { code: 'EINVAL' });
+        expect(formatPackageBinSpawnFailure('npm', ['pack'], {
+            error,
+            status: null,
+            stdout: undefined,
+            stderr: undefined,
+        })).toBe('npm pack failed to start: spawnSync npm EINVAL');
+    });
+});

package/dist/src/session-lease.d.ts

@@ -0,0 +1,82 @@
+/** Inactivity window after which an unowned session lease expires. */
+export declare const SESSION_LEASE_TTL_MS = 45000;
+/** Generate an id for one complete logical CLI command run. */
+export declare function generateRunId(): string;
+export interface DaemonRunContext {
+    runId: string;
+    command: string;
+    access: 'read' | 'write';
+}
+/** Run one logical execution with context isolated across its async chain. */
+export declare function runWithDaemonRunContext<T>(context: DaemonRunContext, callback: () => T): T;
+export declare function setDaemonRunContext(context: DaemonRunContext): void;
+export declare function getDaemonRunContext(): DaemonRunContext | undefined;
+/**
+ * Clear only the context still owned by `runId`. Deferred cleanup from an old
+ * command must not clear a newer command's run identity.
+ */
+export declare function clearDaemonRunContext(runId: string): void;
+/**
+ * Detect errors whose browser-side result is unknown. The traversal includes
+ * wrapper causes and AggregateError members and tolerates cyclic error graphs.
+ */
+export declare function isUnknownOutcomeError(error: unknown): boolean;
+export interface SessionLeaseHolder {
+    command: string;
+    pid?: number;
+    acquiredAt: number;
+    heartbeatAt: number;
+}
+export interface SessionLease extends SessionLeaseHolder {
+    key: string;
+    runId: string;
+}
+/** Public status shape: the internal ownership token is intentionally omitted. */
+export type SessionLeaseStatus = Omit<SessionLease, 'runId'>;
+export interface AcquireSessionLeaseInput {
+    key: string;
+    runId: string;
+    command: string;
+    pid?: number;
+}
+export type AcquireResult = {
+    acquired: true;
+    lease: SessionLease;
+} | {
+    acquired: false;
+    holder: SessionLease;
+};
+/**
+ * Lease key for a site session after the daemon has resolved its actual Cloak
+ * profile. Encoding the session keeps key partitions unambiguous.
+ */
+export declare function getSessionLeaseKey(profileId: string, surface: string, session: string): string;
+/** Whether a process id is safe to interpolate into local process guidance. */
+export declare function isActionablePid(pid: unknown): pid is number;
+export interface SessionLeaseCommand {
+    surface?: unknown;
+    siteSession?: unknown;
+    access?: unknown;
+    session?: unknown;
+    runId?: unknown;
+}
+/** Only persistent adapter writes with a complete owner identity need a lease. */
+export declare function isSessionLeaseCommand<T extends SessionLeaseCommand>(command: T): command is T & {
+    surface: 'adapter';
+    siteSession: 'persistent';
+    access: 'write';
+    session: string;
+    runId: string;
+};
+export declare class SessionLeaseRegistry {
+    private readonly now;
+    private readonly leases;
+    constructor(now?: () => number);
+    acquire(input: AcquireSessionLeaseInput, hasPendingWork: (runId: string) => boolean): AcquireResult;
+    /** Refresh a lease only when both its key and logical owner match. */
+    heartbeat(key: string, runId: string): boolean;
+    /** Release all leases owned by one logical run. */
+    releaseByRunId(runId: string): number;
+    /** Return a snapshot of currently live leases without exposing mutable state. */
+    list(hasPendingWork: (runId: string) => boolean): SessionLease[];
+}

package/dist/src/session-lease.js

@@ -0,0 +1,163 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Inactivity window after which an unowned session lease expires. */
+export const SESSION_LEASE_TTL_MS = 45_000;
+let runIdCounter = 0;
+/** Generate an id for one complete logical CLI command run. */
+export function generateRunId() {
+    return `run_${process.pid}_${Date.now()}_${++runIdCounter}`;
+}
+let activeRun;
+const daemonRunContextStorage = new AsyncLocalStorage();
+/** Run one logical execution with context isolated across its async chain. */
+export function runWithDaemonRunContext(context, callback) {
+    return daemonRunContextStorage.run(context, callback);
+}
+export function setDaemonRunContext(context) {
+    activeRun = context;
+}
+export function getDaemonRunContext() {
+    return daemonRunContextStorage.getStore() ?? activeRun;
+}
+/**
+ * Clear only the context still owned by `runId`. Deferred cleanup from an old
+ * command must not clear a newer command's run identity.
+ */
+export function clearDaemonRunContext(runId) {
+    if (activeRun?.runId === runId)
+        activeRun = undefined;
+}
+const UNKNOWN_OUTCOME_CODES = [
+    'command_result_unknown',
+    'command_lost',
+    'result_evicted',
+];
+function containsUnknownOutcomeCode(value) {
+    if (typeof value !== 'string')
+        return false;
+    const normalized = value.toLowerCase();
+    return UNKNOWN_OUTCOME_CODES.some((code) => {
+        const start = normalized.indexOf(code);
+        if (start < 0)
+            return false;
+        const before = normalized[start - 1];
+        const after = normalized[start + code.length];
+        return (!before || !/[a-z0-9_]/.test(before)) && (!after || !/[a-z0-9_]/.test(after));
+    });
+}
+/**
+ * Detect errors whose browser-side result is unknown. The traversal includes
+ * wrapper causes and AggregateError members and tolerates cyclic error graphs.
+ */
+export function isUnknownOutcomeError(error) {
+    const queue = [error];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current || (typeof current !== 'object' && typeof current !== 'function') || seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const record = current;
+        if (containsUnknownOutcomeCode(record.code)
+            || containsUnknownOutcomeCode(record.errorCode)
+            || containsUnknownOutcomeCode(record.daemonCode)
+            || containsUnknownOutcomeCode(record.message)
+            || containsUnknownOutcomeCode(record.error)) {
+            return true;
+        }
+        if (record.cause !== undefined)
+            queue.push(record.cause);
+        if (Array.isArray(record.errors))
+            queue.push(...record.errors);
+    }
+    return false;
+}
+/**
+ * Lease key for a site session after the daemon has resolved its actual Cloak
+ * profile. Encoding the session keeps key partitions unambiguous.
+ */
+export function getSessionLeaseKey(profileId, surface, session) {
+    return `${profileId}␟${surface}␟${encodeURIComponent(session)}`;
+}
+/** Whether a process id is safe to interpolate into local process guidance. */
+export function isActionablePid(pid) {
+    return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0;
+}
+function pidFromRunId(runId) {
+    const match = /^run_(\d+)_/.exec(runId);
+    if (!match)
+        return undefined;
+    const pid = Number(match[1]);
+    return isActionablePid(pid) ? pid : undefined;
+}
+/** Only persistent adapter writes with a complete owner identity need a lease. */
+export function isSessionLeaseCommand(command) {
+    return command.surface === 'adapter'
+        && command.siteSession === 'persistent'
+        && command.access === 'write'
+        && typeof command.session === 'string'
+        && command.session.length > 0
+        && typeof command.runId === 'string'
+        && command.runId.length > 0;
+}
+export class SessionLeaseRegistry {
+    now;
+    leases = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    acquire(input, hasPendingWork) {
+        const now = this.now();
+        const current = this.leases.get(input.key);
+        const currentIsLive = current !== undefined
+            && (now - current.heartbeatAt <= SESSION_LEASE_TTL_MS || hasPendingWork(current.runId));
+        if (current && currentIsLive && current.runId !== input.runId) {
+            return { acquired: false, holder: { ...current } };
+        }
+        const pid = input.pid === undefined
+            ? pidFromRunId(input.runId)
+            : (isActionablePid(input.pid) ? input.pid : undefined);
+        const lease = current?.runId === input.runId
+            ? { ...current, heartbeatAt: now }
+            : {
+                key: input.key,
+                runId: input.runId,
+                command: input.command,
+                ...(pid === undefined ? {} : { pid }),
+                acquiredAt: now,
+                heartbeatAt: now,
+            };
+        this.leases.set(input.key, lease);
+        return { acquired: true, lease: { ...lease } };
+    }
+    /** Refresh a lease only when both its key and logical owner match. */
+    heartbeat(key, runId) {
+        const current = this.leases.get(key);
+        if (!current || current.runId !== runId)
+            return false;
+        current.heartbeatAt = this.now();
+        return true;
+    }
+    /** Release all leases owned by one logical run. */
+    releaseByRunId(runId) {
+        let released = 0;
+        for (const [key, lease] of this.leases) {
+            if (lease.runId !== runId)
+                continue;
+            this.leases.delete(key);
+            released += 1;
+        }
+        return released;
+    }
+    /** Return a snapshot of currently live leases without exposing mutable state. */
+    list(hasPendingWork) {
+        const now = this.now();
+        const active = [];
+        for (const lease of this.leases.values()) {
+            if (now - lease.heartbeatAt <= SESSION_LEASE_TTL_MS || hasPendingWork(lease.runId)) {
+                active.push({ ...lease });
+            }
+        }
+        return active;
+    }
+}

package/dist/src/session-lease.test.d.ts

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