@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/convention-audit.test.js

@@ -0,0 +1,255 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { renderConventionAuditText, runConventionAudit } from './convention-audit.js';
+describe('convention audit', () => {
+    const tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    function makeProject(manifest, files) {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-convention-audit-'));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, 'clis'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'cli-manifest.json'), JSON.stringify(manifest, null, 2));
+        for (const [relative, content] of Object.entries(files)) {
+            const file = path.join(root, 'clis', relative);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, content);
+        }
+        return root;
+    }
+    it('reports column, metadata, typed-error, and write-pair violations', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title', 'authorName'],
+                sourceFile: 'demo/search.js',
+            },
+            {
+                site: 'demo',
+                name: 'like',
+                access: 'write',
+                sourceFile: 'demo/like.js',
+            },
+            {
+                site: 'demo',
+                name: 'missing',
+                columns: [],
+                sourceFile: 'demo/missing.js',
+            },
+            {
+                site: 'clean',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title'],
+                sourceFile: 'clean/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run(kwargs) {
+          const limit = Math.min(kwargs.limit, 100);
+          try {
+            await fetch('/items');
+          } catch {
+            return [];
+          }
+          rows.push({
+            id: item.id,
+            title: item.title ?? 'unknown',
+            url: item.url,
+            authorName: item.authorName,
+          });
+          return limit;
+        }
+      `,
+            'demo/like.js': 'export async function run() { return { ok: true }; }',
+            'demo/missing.js': 'export async function run() { return { ok: true }; }',
+            'clean/search.js': 'export async function run() { rows.push({ id: item.id, title: item.title }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const category = (rule) => report.categories.find((item) => item.rule === rule);
+        expect(report.ok).toBe(false);
+        expect(category('silent-column-drop').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+        expect(category('camelCase-in-columns').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: { column: 'authorName' },
+        });
+        expect(category('missing-access-metadata').violations[0]).toMatchObject({ command: 'demo/missing' });
+        expect(category('silent-clamp').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-empty-fallback').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-sentinel').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('write-without-delete-pair').violations[0]).toMatchObject({
+            command: 'demo/like',
+            details: { expected_any_of: ['unlike'] },
+        });
+    });
+    it('supports site and command target filters', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+            { site: 'other', name: 'search', access: 'read', columns: ['id'], sourceFile: 'other/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+            'other/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+        });
+        expect(runConventionAudit({ projectRoot: root, site: 'demo' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'other/search' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'missing' }).summary.commands).toBe(0);
+    });
+    it('renders a compact text report', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1 }); }',
+        });
+        const text = renderConventionAuditText(runConventionAudit({ projectRoot: root }));
+        expect(text).toContain('Convention Audit Report');
+        expect(text).toContain('OK - no convention violations found.');
+    });
+    it('scans pipeline map blocks for silent column drops', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'feed', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/feed.js' },
+        ], {
+            'demo/feed.js': `
+        cli({
+          site: 'demo',
+          name: 'feed',
+          access: 'read',
+          columns: ['id', 'title'],
+          pipeline: [
+            { map: {
+              id: '\${{ item.id }}',
+              title: '\${{ item.title }}',
+              url: '\${{ item.url }}',
+            } },
+          ],
+        });
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/feed',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+    });
+    it('ignores ok:false diagnostic objects when checking emitted rows', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'url'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          if (!document.querySelector('.items')) {
+            return { ok: false, bodyLen: document.body.innerText.length, sample: document.body.innerText.slice(0, 800), url: location.href };
+          }
+          return rows.map((row) => ({ id: row.id, url: row.url }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('ignores raw intermediate keys when a final mapper converts them into columns', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'rating', 'reviews', 'price'],
+                sourceFile: 'demo/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            starClass: item.starClass,
+            reviewsRaw: item.reviewsRaw,
+            priceRaw: item.priceRaw,
+          });
+          return rows.map((r) => ({
+            id: r.id,
+            rating: r.starClass ? Number(r.starClass) / 10 : null,
+            reviews: parseReviewCount(r.reviewsRaw),
+            price: parsePrice(r.priceRaw),
+          }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('still reports raw keys emitted directly without a final mapper', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            title: titleRaw,
+            titleRaw,
+          });
+          return rows;
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['titleRaw'] }),
+        });
+    });
+    it('only reports empty array fallbacks inside catch blocks', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'guard', access: 'read', columns: ['id'], sourceFile: 'demo/guard.js' },
+            { site: 'demo', name: 'catch', access: 'read', columns: ['id'], sourceFile: 'demo/catch.js' },
+        ], {
+            'demo/guard.js': 'export async function run() { if (!store) return []; rows.push({ id: 1 }); }',
+            'demo/catch.js': 'export async function run() { try { await fetch("/"); } catch (err) { return []; } rows.push({ id: 1 }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-empty-fallback').violations;
+        expect(violations.map((violation) => violation.command)).toEqual(['demo/catch']);
+    });
+    it('does not report sentinel fallbacks inside thrown error messages', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'error', access: 'read', columns: ['id'], sourceFile: 'demo/error.js' },
+            { site: 'demo', name: 'row', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/row.js' },
+        ], {
+            'demo/error.js': `
+        export async function run(data) {
+          if (!data.ok) throw new Error(\`demo failed: \${data.message ?? 'unknown'}\`);
+          return [{ id: 1 }];
+        }
+      `,
+            'demo/row.js': `
+        export async function run(item) {
+          return [{ id: item.id, title: item.title ?? 'unknown' }];
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-sentinel').violations;
+        expect(violations.map((violation) => violation.command)).toEqual(['demo/row']);
+    });
+});
+describe('extension removal audit', () => {
+    it('does not ship the old browser extension package', () => {
+        expect(fs.existsSync(path.join(process.cwd(), 'extension', 'manifest.json'))).toBe(false);
+    });
+    it('does not keep extension-only e2e smoke tests', () => {
+        expect(fs.existsSync(path.join(process.cwd(), 'tests/e2e/browser-ax-chrome.test.ts'))).toBe(false);
+    });
+});

package/dist/src/daemon/server.d.ts

@@ -0,0 +1,13 @@
+import { type Server } from 'node:http';
+import type { BrowserRuntimeProvider } from '../browser/runtime/provider.js';
+export interface DaemonServerOptions {
+    port?: number;
+    host?: string;
+    version: string;
+}
+export interface DaemonServerHandle {
+    server: Server;
+    listen(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createDaemonServer(provider: BrowserRuntimeProvider, opts: DaemonServerOptions): DaemonServerHandle;

package/dist/src/daemon/server.js

@@ -0,0 +1,190 @@
+import { createServer } from 'node:http';
+import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
+import { buildCommandTimeoutFailure, getResponseCorsHeaders } from '../daemon-utils.js';
+const MAX_BODY = 1024 * 1024;
+const LOG_BUFFER_SIZE = 200;
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let aborted = false;
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_BODY) {
+                aborted = true;
+                req.destroy();
+                reject(new Error('Body too large'));
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            if (!aborted)
+                resolve(Buffer.concat(chunks).toString('utf-8'));
+        });
+        req.on('error', (err) => {
+            if (!aborted)
+                reject(err);
+        });
+    });
+}
+function jsonResponse(res, status, data, extraHeaders) {
+    res.writeHead(status, { 'Content-Type': 'application/json', ...extraHeaders });
+    res.end(JSON.stringify(data));
+}
+export function createDaemonServer(provider, opts) {
+    const port = opts.port ?? DEFAULT_DAEMON_PORT;
+    const host = opts.host ?? '127.0.0.1';
+    const logBuffer = [];
+    const pending = new Map();
+    let shutdownStarted = false;
+    function pushLog(level, msg) {
+        logBuffer.push({ level, msg, ts: Date.now() });
+        if (logBuffer.length > LOG_BUFFER_SIZE)
+            logBuffer.shift();
+    }
+    async function shutdownProvider() {
+        if (shutdownStarted)
+            return;
+        shutdownStarted = true;
+        await provider.shutdown();
+    }
+    async function handleRequest(req, res) {
+        const origin = req.headers.origin;
+        if (origin && !origin.startsWith('chrome-extension://')) {
+            jsonResponse(res, 403, { ok: false, error: 'Forbidden: cross-origin request blocked' });
+            return;
+        }
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = req.url ?? '/';
+        const pathname = url.split('?')[0];
+        if (req.method === 'GET' && pathname === '/ping') {
+            jsonResponse(res, 200, { ok: true }, getResponseCorsHeaders(pathname, origin));
+            return;
+        }
+        if (!req.headers[DAEMON_HEADER_NAME.toLowerCase()]) {
+            jsonResponse(res, 403, { ok: false, error: `Forbidden: missing ${DAEMON_HEADER_NAME} header` });
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/status') {
+            const mem = process.memoryUsage();
+            const params = new URL(url, `http://localhost:${port}`).searchParams;
+            const contextId = params.get('contextId')?.trim() || undefined;
+            const runtime = await provider.status({ contextId });
+            jsonResponse(res, 200, {
+                ok: true,
+                pid: process.pid,
+                uptime: process.uptime(),
+                daemonVersion: opts.version,
+                ...runtime,
+                pending: pending.size + runtime.pending,
+                memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
+                port,
+            });
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/logs') {
+            const params = new URL(url, `http://localhost:${port}`).searchParams;
+            const level = params.get('level');
+            const logs = level ? logBuffer.filter((entry) => entry.level === level) : logBuffer;
+            jsonResponse(res, 200, { ok: true, logs });
+            return;
+        }
+        if (req.method === 'DELETE' && pathname === '/logs') {
+            logBuffer.length = 0;
+            jsonResponse(res, 200, { ok: true });
+            return;
+        }
+        if (req.method === 'POST' && pathname === '/shutdown') {
+            jsonResponse(res, 200, { ok: true, message: 'Shutting down' });
+            setTimeout(() => {
+                shutdownProvider().finally(() => {
+                    server.close();
+                });
+            }, 10);
+            return;
+        }
+        if (req.method === 'POST' && pathname === '/command') {
+            try {
+                const body = JSON.parse(await readBody(req));
+                if (!body.id) {
+                    jsonResponse(res, 400, { ok: false, error: 'Missing command id' });
+                    return;
+                }
+                const existing = pending.get(body.id);
+                if (existing) {
+                    const result = await existing;
+                    jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
+                    return;
+                }
+                const timeoutMs = typeof body.deadlineAt === 'number' && body.deadlineAt > 0
+                    ? Math.max(1000, body.deadlineAt - Date.now())
+                    : (typeof body.timeout === 'number' && body.timeout > 0 ? body.timeout * 1000 : 120_000);
+                let timeoutId;
+                const commandPromise = Promise.race([
+                    provider.dispatch(body),
+                    new Promise((resolve) => {
+                        timeoutId = setTimeout(() => {
+                            const failure = buildCommandTimeoutFailure(body.action, timeoutMs);
+                            resolve({
+                                id: body.id,
+                                ok: false,
+                                errorCode: failure.errorCode,
+                                error: failure.message,
+                                errorHint: failure.errorHint,
+                            });
+                        }, timeoutMs);
+                    }),
+                ]).finally(() => {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    pending.delete(body.id);
+                });
+                pending.set(body.id, commandPromise);
+                const result = await commandPromise;
+                if (!result.ok)
+                    pushLog('warn', `Command ${body.id} failed: ${result.error ?? result.errorCode ?? 'unknown error'}`);
+                jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
+            }
+            catch (err) {
+                jsonResponse(res, 400, { ok: false, error: err instanceof Error ? err.message : 'Invalid request' });
+            }
+            return;
+        }
+        jsonResponse(res, 404, { error: 'Not found' });
+    }
+    const server = createServer((req, res) => {
+        handleRequest(req, res).catch((err) => {
+            jsonResponse(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    return {
+        server,
+        listen: () => new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, host, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        }),
+        close: async () => {
+            await shutdownProvider();
+            await new Promise((resolve, reject) => {
+                if (!server.listening) {
+                    resolve();
+                    return;
+                }
+                server.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}

package/dist/src/daemon/server.test.d.ts

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

package/dist/src/daemon/server.test.js

@@ -0,0 +1,184 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DAEMON_HEADER_NAME } from '../constants.js';
+import { createDaemonServer } from './server.js';
+class FakeProvider {
+    commands = [];
+    shutdownCalled = false;
+    delayMs = 0;
+    async status() {
+        return {
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            runtimeVersion: '1.2.3',
+            profiles: [{ contextId: 'default', runtimeConnected: true, runtimeVersion: '1.2.3', pending: 0 }],
+            pending: 0,
+            commandResultUnknown: 0,
+        };
+    }
+    async dispatch(command) {
+        if (this.delayMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, this.delayMs));
+        this.commands.push(command);
+        return { id: command.id, ok: true, data: { action: command.action }, page: 'page-1' };
+    }
+    async shutdown() {
+        this.shutdownCalled = true;
+    }
+}
+describe('createDaemonServer', () => {
+    const servers = [];
+    afterEach(async () => {
+        while (servers.length)
+            await servers.pop().close();
+    });
+    async function start(provider = new FakeProvider()) {
+        const daemon = createDaemonServer(provider, { port: 0, host: '127.0.0.1', version: 'test' });
+        await daemon.listen();
+        servers.push(daemon);
+        const address = daemon.server.address();
+        return { provider, baseUrl: `http://127.0.0.1:${address.port}` };
+    }
+    it('returns runtime-named status fields without extension aliases', async () => {
+        const { baseUrl } = await start();
+        const res = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+        const body = await res.json();
+        expect(body).toMatchObject({
+            ok: true,
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            runtimeVersion: '1.2.3',
+            profiles: [{ contextId: 'default', runtimeConnected: true }],
+        });
+        expect(body).not.toHaveProperty(`extension${'Connected'}`);
+        expect(body).not.toHaveProperty(`extension${'Version'}`);
+    });
+    it('dispatches /command through the provider', async () => {
+        const { provider, baseUrl } = await start();
+        const res = await fetch(`${baseUrl}/command`, {
+            method: 'POST',
+            headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id: 'cmd-1', action: 'navigate', session: 'work', url: 'https://example.com' }),
+        });
+        await expect(res.json()).resolves.toEqual({
+            id: 'cmd-1',
+            ok: true,
+            data: { action: 'navigate' },
+            page: 'page-1',
+        });
+        expect(provider.commands).toHaveLength(1);
+        expect(provider.commands[0]).toMatchObject({ id: 'cmd-1', action: 'navigate', session: 'work' });
+    });
+    it('clears custom command timeout timers after successful provider dispatch', async () => {
+        const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+        const clearTimeoutSpy = vi.spyOn(globalThis, 'clearTimeout');
+        try {
+            const { baseUrl } = await start();
+            const res = await fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body: JSON.stringify({ id: 'fast-custom-timeout', action: 'navigate', session: 'work', timeout: 60 }),
+            });
+            expect(res.status).toBe(200);
+            await expect(res.json()).resolves.toMatchObject({
+                id: 'fast-custom-timeout',
+                ok: true,
+            });
+            const timeoutCallIndex = setTimeoutSpy.mock.calls.findIndex(([, delay]) => delay === 60_000);
+            expect(timeoutCallIndex).toBeGreaterThanOrEqual(0);
+            const commandTimeoutHandle = setTimeoutSpy.mock.results[timeoutCallIndex]?.value;
+            expect(clearTimeoutSpy).toHaveBeenCalledWith(commandTimeoutHandle);
+        }
+        finally {
+            setTimeoutSpy.mockRestore();
+            clearTimeoutSpy.mockRestore();
+        }
+    });
+    it('uses deadlineAt as the command timeout budget when present', async () => {
+        const now = 1_763_000_000_000;
+        const dateSpy = vi.spyOn(Date, 'now').mockReturnValue(now);
+        const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+        try {
+            const { baseUrl } = await start();
+            const res = await fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    id: 'deadline-command',
+                    action: 'exec',
+                    session: 'work',
+                    timeout: 120,
+                    deadlineAt: now + 12_345,
+                }),
+            });
+            expect(res.status).toBe(200);
+            await expect(res.json()).resolves.toMatchObject({
+                id: 'deadline-command',
+                ok: true,
+            });
+            expect(setTimeoutSpy.mock.calls.some(([, delay]) => delay === 12_345)).toBe(true);
+        }
+        finally {
+            setTimeoutSpy.mockRestore();
+            dateSpy.mockRestore();
+        }
+    });
+    it('attaches duplicate command ids to the in-flight dispatch instead of re-dispatching', async () => {
+        const provider = new FakeProvider();
+        provider.delayMs = 50;
+        const { baseUrl } = await start(provider);
+        const body = JSON.stringify({ id: 'same-id', action: 'exec', session: 'work', code: '1' });
+        const [first, second] = await Promise.all([
+            fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body,
+            }),
+            fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body,
+            }),
+        ]);
+        expect(first.status).toBe(200);
+        expect(second.status).toBe(200);
+        await expect(first.json()).resolves.toMatchObject({ id: 'same-id', ok: true });
+        await expect(second.json()).resolves.toMatchObject({ id: 'same-id', ok: true });
+        expect(provider.commands).toHaveLength(1);
+    });
+    it('requires X-Webcmd on non-ping endpoints', async () => {
+        const { baseUrl } = await start();
+        const res = await fetch(`${baseUrl}/status`);
+        expect(res.status).toBe(403);
+    });
+    it('records daemon logs through /logs', async () => {
+        const { baseUrl } = await start();
+        const res = await fetch(`${baseUrl}/logs`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+        const body = await res.json();
+        expect(body).toMatchObject({ ok: true, logs: expect.any(Array) });
+    });
+    it('times out slow provider commands and clears pending state', async () => {
+        const provider = new FakeProvider();
+        provider.delayMs = 100;
+        const { baseUrl } = await start(provider);
+        const res = await fetch(`${baseUrl}/command`, {
+            method: 'POST',
+            headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id: 'slow', action: 'exec', session: 'work', timeout: 0.01 }),
+        });
+        expect(res.status).toBe(408);
+        await expect(res.json()).resolves.toMatchObject({
+            id: 'slow',
+            ok: false,
+            errorCode: 'command_result_unknown',
+        });
+    });
+    it('calls provider shutdown before closing', async () => {
+        const { provider, baseUrl } = await start();
+        const res = await fetch(`${baseUrl}/shutdown`, {
+            method: 'POST',
+            headers: { [DAEMON_HEADER_NAME]: '1' },
+        });
+        expect(res.status).toBe(200);
+        await vi.waitFor(() => expect(provider.shutdownCalled).toBe(true));
+    });
+});

package/dist/src/daemon-utils.d.ts

@@ -0,0 +1,19 @@
+export declare const COMMAND_RESULT_UNKNOWN_CODE = "command_result_unknown";
+export declare const COMMAND_RESULT_UNKNOWN_HINT = "Inspect the browser/session state before retrying. Do not blindly retry write commands such as navigate, click, type, or eval.";
+export declare const PROFILE_DISCONNECTED_HINT = "Open that Chrome profile and make sure the Webcmd extension is enabled, or choose another profile with webcmd profile use <name>.";
+export type DaemonFailureContract = {
+    message: string;
+    errorCode: string;
+    errorHint: string;
+    status: number;
+    countAsCommandResultUnknown: boolean;
+};
+export declare function commandResultUnknownMessage(action: string): string;
+export declare function buildExtensionDisconnectFailure(input: {
+    contextId: string;
+    action: string;
+    dispatched: boolean;
+}): DaemonFailureContract;
+export declare function buildCommandTimeoutFailure(action: string, timeoutMs: number): DaemonFailureContract;
+export declare function buildCommandDispatchFailure(contextId: string): DaemonFailureContract;
+export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;