@minionry/minion 0.7.36

package/dist/server/mcp/test-utils/agent-simulator.js

@@ -0,0 +1,301 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { TabAlreadyLeasedError, } from '../../services/browser/host-mock.js';
+import { callTool, LeaseManager, } from '../browser-mcp-server.js';
+export class HostBackedClient {
+    host;
+    identity;
+    calls = [];
+    maxCalls = 10_000;
+    constructor(host, identity) {
+        this.host = host;
+        this.identity = identity;
+    }
+    async call(method, params = {}) {
+        this.recordCall(method);
+        try {
+            const p = this.stampIdentity(params);
+            switch (method) {
+                case 'agent.tab.lease': {
+                    const result = await this.host.leaseTab(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'agent.tab.heartbeat': {
+                    const result = await this.host.heartbeat(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'agent.tab.release': {
+                    const result = await this.host.releaseTab(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'agent.tab.list': {
+                    const result = await this.host.listLeases(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'dom.snapshot': {
+                    const result = await this.host.dom.snapshot(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'dom.click': {
+                    await this.host.dom.click(p);
+                    return { status: 200, body: { result: null } };
+                }
+                case 'dom.type': {
+                    await this.host.dom.type(p);
+                    return { status: 200, body: { result: null } };
+                }
+                case 'dom.hover': {
+                    await this.host.dom.hover(p);
+                    return { status: 200, body: { result: null } };
+                }
+                case 'dom.screenshot': {
+                    const result = await this.host.dom.screenshot(p);
+                    return { status: 200, body: { result } };
+                }
+                case 'tab.open': {
+                    const url = typeof params.url === 'string' ? params.url : 'about:blank';
+                    const out = await this.host.openTab(url);
+                    return { status: 200, body: { result: { id: out.id } } };
+                }
+                case 'tab.close': {
+                    await this.host.closeTab(String(params.id ?? ''));
+                    return { status: 200, body: { result: null } };
+                }
+                case 'tab.select': {
+                    await this.host.switchTab(String(params.id ?? ''));
+                    return { status: 200, body: { result: null } };
+                }
+                default:
+                    return {
+                        status: 500,
+                        body: {
+                            error: {
+                                code: 'method_not_implemented',
+                                message: `HostBackedClient does not support ${method}`,
+                            },
+                        },
+                    };
+            }
+        }
+        catch (err) {
+            if (err instanceof TabAlreadyLeasedError) {
+                return {
+                    status: 409,
+                    body: {
+                        error: {
+                            code: 'tab_already_leased',
+                            message: err.message,
+                            data: { currentOwner: err.currentOwner },
+                        },
+                    },
+                };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                status: 500,
+                body: { error: { code: 'internal_error', message } },
+            };
+        }
+    }
+    stampIdentity(params) {
+        return {
+            ...params,
+            agentId: this.identity.agentId,
+            ...(this.identity.planId !== undefined ? { planId: this.identity.planId } : {}),
+        };
+    }
+    recordCall(method) {
+        if (this.calls.length >= this.maxCalls)
+            this.calls.shift();
+        this.calls.push({ method, ts: Date.now() });
+    }
+}
+export class LatencyHistogram {
+    samples = [];
+    record(ms) {
+        this.samples.push(ms);
+    }
+    count() {
+        return this.samples.length;
+    }
+    percentile(p) {
+        if (this.samples.length === 0)
+            return 0;
+        const sorted = [...this.samples].sort((a, b) => a - b);
+        const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+        return sorted[idx] ?? 0;
+    }
+    max() {
+        if (this.samples.length === 0)
+            return 0;
+        let m = this.samples[0] ?? 0;
+        for (const s of this.samples)
+            if (s > m)
+                m = s;
+        return m;
+    }
+}
+export const RANDOM_OPS = [
+    'snapshot',
+    'click',
+    'type',
+    'hover',
+    'screenshot',
+];
+export class AgentSimulator {
+    agentId;
+    planId;
+    tabIds;
+    leases;
+    ctx;
+    client;
+    latencies = {
+        snapshot: new LatencyHistogram(),
+        click: new LatencyHistogram(),
+        type: new LatencyHistogram(),
+        hover: new LatencyHistogram(),
+        screenshot: new LatencyHistogram(),
+    };
+    errors = [];
+    rng;
+    log;
+    heartbeatHandle = null;
+    killed = false;
+    constructor(opts) {
+        this.agentId = opts.agentId;
+        this.planId = opts.planId;
+        this.tabIds = [...opts.tabIds];
+        this.rng = opts.rng ?? Math.random;
+        this.log = opts.log ?? (() => { });
+        this.client = new HostBackedClient(opts.host, {
+            agentId: opts.agentId,
+            ...(opts.planId !== undefined ? { planId: opts.planId } : {}),
+        });
+        this.leases = new LeaseManager({
+            client: this.client,
+            log: this.log,
+            setIntervalFn: (handler, ms) => {
+                const h = setInterval(() => {
+                    if (!this.killed)
+                        handler();
+                }, ms);
+                h.unref?.();
+                this.heartbeatHandle = h;
+                return h;
+            },
+            clearIntervalFn: (handle) => {
+                clearInterval(handle);
+                if (this.heartbeatHandle === handle) {
+                    this.heartbeatHandle = null;
+                }
+            },
+            heartbeatIntervalMs: opts.heartbeatIntervalMs ?? 1_000,
+        });
+        this.ctx = {
+            client: this.client,
+            leases: this.leases,
+            log: this.log,
+        };
+    }
+    async leaseAll() {
+        for (const tabId of this.tabIds) {
+            await this.leases.ensure(tabId);
+        }
+        this.leases.start();
+    }
+    async step() {
+        const op = RANDOM_OPS[Math.floor(this.rng() * RANDOM_OPS.length)] ?? 'snapshot';
+        const tabId = this.tabIds[Math.floor(this.rng() * this.tabIds.length)] ?? this.tabIds[0];
+        const start = process.hrtime.bigint();
+        const result = await this.invoke(op, tabId);
+        const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+        if (result.isError) {
+            const meta = (result._meta ?? {});
+            const code = meta.errorCode ?? 'unknown_error';
+            const message = result.content[0] && result.content[0].type === 'text'
+                ? result.content[0].text
+                : undefined;
+            this.errors.push({
+                op,
+                code,
+                ...(message !== undefined ? { message } : {}),
+            });
+            return {
+                op,
+                tabId,
+                durationMs,
+                ok: false,
+                errorCode: code,
+            };
+        }
+        this.latencies[op].record(durationMs);
+        return { op, tabId, durationMs, ok: true };
+    }
+    async runFor(durationMs, opCount) {
+        if (opCount <= 0)
+            return;
+        const interval = durationMs / opCount;
+        const startedAt = Date.now();
+        for (let i = 0; i < opCount; i++) {
+            if (this.killed)
+                return;
+            const target = startedAt + i * interval;
+            const now = Date.now();
+            if (now < target)
+                await sleep(target - now);
+            await this.step();
+        }
+    }
+    kill() {
+        if (this.killed)
+            return;
+        this.killed = true;
+        if (this.heartbeatHandle) {
+            clearInterval(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+    }
+    isKilled() {
+        return this.killed;
+    }
+    async shutdown() {
+        if (this.killed) {
+            return;
+        }
+        await this.leases.stop();
+    }
+    async invoke(op, tabId) {
+        switch (op) {
+            case 'snapshot':
+                return callTool(this.ctx, 'browser_snapshot', { tabId });
+            case 'click':
+                return callTool(this.ctx, 'browser_click', { tabId, ref: 'e1n2' });
+            case 'type':
+                return callTool(this.ctx, 'browser_type', {
+                    tabId,
+                    ref: 'e1n2',
+                    text: 'stress',
+                });
+            case 'hover':
+                return callTool(this.ctx, 'browser_hover', { tabId, ref: 'e1n2' });
+            case 'screenshot':
+                return callTool(this.ctx, 'browser_take_screenshot', { tabId });
+        }
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        t.unref?.();
+    });
+}
+export function makeRng(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/server/mcp/test-utils/e2e-agent.js

@@ -0,0 +1,103 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { MockBrowserHost } from '../../services/browser/host-mock.js';
+import { callTool, LeaseManager, } from '../browser-mcp-server.js';
+import { GoldenFixtureClient } from './e2e-client.js';
+export class StderrCollector {
+    stderr = [];
+    sentryEvents = [];
+    originalError = null;
+    capture() {
+        this.originalError = console.error;
+        console.error = (...args) => {
+            const message = args
+                .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
+                .join(' ');
+            this.stderr.push(message);
+        };
+    }
+    recordSentry(message) {
+        this.sentryEvents.push({ message });
+    }
+    restore() {
+        if (this.originalError) {
+            console.error = this.originalError;
+            this.originalError = null;
+        }
+    }
+}
+export class E2EAgent {
+    agentId;
+    planId;
+    client;
+    leases;
+    ctx;
+    constructor(opts) {
+        this.agentId = opts.agentId;
+        this.planId = opts.planId;
+        this.client = new GoldenFixtureClient(opts.host, {
+            agentId: opts.agentId,
+            ...(opts.planId !== undefined ? { planId: opts.planId } : {}),
+        });
+        const log = opts.log ?? (() => { });
+        this.leases = new LeaseManager({
+            client: this.client,
+            log,
+            heartbeatIntervalMs: opts.heartbeatIntervalMs ?? 250,
+        });
+        this.ctx = {
+            client: this.client,
+            leases: this.leases,
+            log,
+        };
+    }
+    async openTab(initialUrl = 'about:blank') {
+        const response = await this.client.call('tab.open', { url: initialUrl });
+        if (response.status !== 200 || !response.body.result) {
+            throw new Error(`tab.open failed: ${response.body.error?.message ?? 'unknown'}`);
+        }
+        const result = response.body.result;
+        return result.id;
+    }
+    async runTool(name, args) {
+        return callTool(this.ctx, name, args);
+    }
+    async shutdown() {
+        await this.leases.stop();
+    }
+}
+export function createE2EHarness() {
+    const host = new MockBrowserHost();
+    const stderr = new StderrCollector();
+    stderr.capture();
+    const agents = [];
+    return {
+        host,
+        stderr,
+        spawnAgent(opts) {
+            const agent = new E2EAgent({ host, ...opts });
+            agents.push(agent);
+            return agent;
+        },
+        async teardown() {
+            for (const agent of agents) {
+                try {
+                    await agent.shutdown();
+                }
+                catch {
+                }
+            }
+            stderr.restore();
+        },
+    };
+}
+export function extractText(result) {
+    const first = result.content[0];
+    if (!first || first.type !== 'text')
+        return '';
+    return first.text;
+}
+export function firstLinkLabel(snapshotYaml) {
+    const match = snapshotYaml.match(/link "([^"]+)"/);
+    return match?.[1];
+}

package/dist/server/mcp/test-utils/e2e-capture.js

@@ -0,0 +1,92 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export function byteVariance(bytes) {
+    if (bytes.length === 0)
+        return 0;
+    let sum = 0;
+    for (let i = 0; i < bytes.length; i++)
+        sum += bytes[i] ?? 0;
+    const mean = sum / bytes.length;
+    let sq = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        const d = (bytes[i] ?? 0) - mean;
+        sq += d * d;
+    }
+    return sq / bytes.length;
+}
+export class FrameReceiver {
+    frames = [];
+    intervalMs;
+    maxFrames;
+    nowMs;
+    source;
+    timer = null;
+    stopped = false;
+    inFlight = null;
+    constructor(opts) {
+        this.source = opts.source;
+        this.intervalMs = opts.intervalMs ?? 1_000;
+        this.maxFrames = opts.maxFrames ?? 30;
+        this.nowMs = opts.nowMs ?? Date.now;
+    }
+    start() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => void this.tick(), this.intervalMs);
+        this.timer.unref?.();
+    }
+    async captureOnce() {
+        if (this.stopped || this.frames.length >= this.maxFrames)
+            return null;
+        const bytes = await this.source();
+        const frame = {
+            capturedAtMs: this.nowMs(),
+            bytes,
+            variance: byteVariance(bytes),
+        };
+        this.frames.push(frame);
+        return frame;
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.inFlight)
+            await this.inFlight.catch(() => { });
+    }
+    nonBlackFrames() {
+        return this.frames.filter((f) => f.variance > 0);
+    }
+    async tick() {
+        if (this.stopped || this.frames.length >= this.maxFrames)
+            return;
+        if (this.inFlight)
+            return;
+        this.inFlight = (async () => {
+            try {
+                await this.captureOnce();
+            }
+            finally {
+                this.inFlight = null;
+            }
+        })();
+    }
+}
+export async function createOrchestraWorkdir(orchestraId) {
+    const base = await mkdtemp(join(tmpdir(), `minionry-e2e-${orchestraId}-`));
+    return {
+        path: base,
+        async cleanup() {
+            try {
+                await rm(base, { recursive: true, force: true });
+            }
+            catch {
+            }
+        },
+    };
+}

package/dist/server/mcp/test-utils/e2e-client.js

@@ -0,0 +1,116 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { HostBackedClient } from './agent-simulator.js';
+import { findClickNavigation, findFixture, NON_BLACK_PNG_BASE64, } from './e2e-fixtures.js';
+export class GoldenFixtureClient {
+    host;
+    calls = [];
+    currentUrl = null;
+    inner;
+    handlers;
+    constructor(host, identity) {
+        this.host = host;
+        this.inner = new HostBackedClient(host, identity);
+        this.handlers = {
+            'view.navigate': (params) => this.handleNavigate(params),
+            'dom.snapshot': () => this.handleSnapshot(),
+            'dom.click': (params) => this.handleClick(params),
+            'dom.screenshot': () => this.handleScreenshot(),
+            'tab.list': (params) => this.handleTabList(params),
+        };
+    }
+    async call(method, params = {}) {
+        this.calls.push({ method, params });
+        const handler = this.handlers[method];
+        if (handler)
+            return handler(params);
+        return this.inner.call(method, params);
+    }
+    handleNavigate(params) {
+        const url = typeof params.url === 'string' ? params.url : '';
+        if (!findFixture(url)) {
+            return {
+                status: 502,
+                body: {
+                    error: {
+                        code: 'fixture_missing',
+                        message: `No golden fixture for ${url}; add one to GOLDEN_FIXTURES`,
+                    },
+                },
+            };
+        }
+        this.currentUrl = url;
+        return { status: 200, body: { result: { url } } };
+    }
+    handleSnapshot() {
+        if (!this.currentUrl) {
+            return {
+                status: 409,
+                body: {
+                    error: {
+                        code: 'no_url_loaded',
+                        message: 'agent has not navigated yet',
+                    },
+                },
+            };
+        }
+        const fixture = findFixture(this.currentUrl);
+        if (!fixture) {
+            return {
+                status: 502,
+                body: {
+                    error: {
+                        code: 'fixture_missing',
+                        message: `No golden fixture for ${this.currentUrl}`,
+                    },
+                },
+            };
+        }
+        return {
+            status: 200,
+            body: {
+                result: {
+                    url: this.currentUrl,
+                    title: '',
+                    epoch: 1,
+                    text: fixture.snapshotText,
+                    root: { ref: 'e1', role: 'generic', children: [] },
+                },
+            },
+        };
+    }
+    async handleClick(params) {
+        const ref = typeof params.ref === 'string' ? params.ref : '';
+        if (this.currentUrl) {
+            const nav = findClickNavigation(this.currentUrl, ref);
+            if (nav)
+                this.currentUrl = nav.toUrl;
+        }
+        await this.inner.call('dom.click', params);
+        return { status: 200, body: { result: null } };
+    }
+    handleScreenshot() {
+        return {
+            status: 200,
+            body: {
+                result: { format: 'png', data: NON_BLACK_PNG_BASE64 },
+            },
+        };
+    }
+    handleTabList(params) {
+        const tabIds = Array.isArray(params.tabIds) ? params.tabIds : [];
+        return {
+            status: 200,
+            body: {
+                result: tabIds.map((id) => ({
+                    tabId: id,
+                    url: this.currentUrl ?? 'about:blank',
+                    title: '',
+                })),
+            },
+        };
+    }
+    currentUrlSnapshot() {
+        return this.currentUrl;
+    }
+}

package/dist/server/mcp/test-utils/e2e-fixtures.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { promises as fs } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const GOLDEN_FIXTURES = [
+    {
+        url: 'https://news.ycombinator.com/',
+        headline: 'Minionry launches browser-native MCP server',
+        snapshotText: [
+            '- generic [ref=e1]:',
+            '  - heading "Hacker News" [level=1] [ref=e2]',
+            '  - list [ref=e3]:',
+            '    - listitem [ref=e4]:',
+            '      - link "Minionry launches browser-native MCP server" [ref=e5]',
+            '      - text "(minionry.com)" [ref=e6]',
+            '    - listitem [ref=e7]:',
+            '      - link "Bun 1.5 release notes" [ref=e8]',
+        ].join('\n'),
+    },
+    {
+        url: 'https://en.wikipedia.org/wiki/Alan_Turing',
+        snapshotText: [
+            '- generic [ref=e1]:',
+            '  - heading "Alan Turing" [level=1] [ref=e2]',
+            '  - paragraph [ref=e3]:',
+            '    - text "Alan Mathison Turing was an English mathematician..."',
+        ].join('\n'),
+    },
+    {
+        url: 'https://en.wikipedia.org/wiki/Grace_Hopper',
+        snapshotText: [
+            '- generic [ref=e1]:',
+            '  - heading "Grace Hopper" [level=1] [ref=e2]',
+            '  - paragraph [ref=e3]:',
+            '    - text "Grace Brewster Hopper was an American computer scientist..."',
+        ].join('\n'),
+    },
+    {
+        url: 'https://www.youtube.com/',
+        snapshotText: [
+            '- generic [ref=e1]:',
+            '  - banner [ref=e2]:',
+            '    - heading "YouTube" [level=1] [ref=e3]',
+            '  - navigation [ref=e9]:',
+            '    - link "Home" [ref=e9a]',
+            '    - link "Trending" [ref=e10]',
+            '    - link "Subscriptions" [ref=e11]',
+        ].join('\n'),
+    },
+    {
+        url: 'https://www.youtube.com/feed/trending',
+        snapshotText: [
+            '- generic [ref=e1]:',
+            '  - heading "Trending" [level=1] [ref=e2]',
+            '  - region "Trending now" [ref=e3]:',
+            '    - list [ref=e4]:',
+            '      - listitem [ref=e5]: link "Trending video 1" [ref=e5a]',
+            '      - listitem [ref=e6]: link "Trending video 2" [ref=e6a]',
+            '      - listitem [ref=e7]: link "Trending video 3" [ref=e7a]',
+        ].join('\n'),
+    },
+];
+export const CLICK_NAVIGATIONS = [
+    {
+        fromUrl: 'https://www.youtube.com/',
+        ref: 'e10',
+        toUrl: 'https://www.youtube.com/feed/trending',
+    },
+];
+export function findClickNavigation(fromUrl, ref) {
+    return CLICK_NAVIGATIONS.find((c) => c.fromUrl === fromUrl && c.ref === ref);
+}
+export function findFixture(url) {
+    return GOLDEN_FIXTURES.find((f) => f.url === url);
+}
+export const NON_BLACK_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mP4z8AAAAMBAQAdq24pAAAAAElFTkSuQmCC';
+export const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+export function decodeBase64Png(base64) {
+    return Uint8Array.from(Buffer.from(base64, 'base64'));
+}
+export async function readGoldenJson(filename) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const path = resolve(here, '..', 'fixtures', 'e2e', filename);
+    const raw = await fs.readFile(path, 'utf-8');
+    return JSON.parse(raw);
+}