agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/commands.js

@@ -0,0 +1,366 @@
+import { formatAction, formatClose, formatInspect, formatObservation, formatScan, formatStart, formatSweep, formatTabs } from './format.js';
+import { scanSummary } from './scan.js';
+import { SWEEP_DEVICES } from './devices.js';
+import { Lab } from './lab.js';
+import { LabError } from './schema.js';
+import { stopReason } from './control.js';
+/** Bounds applied when a property sets none, so no argument is unbounded (MCP input is untrusted). */
+const DEFAULT_MAX_LENGTH = 4096;
+const DEFAULT_MAX_ITEMS = 100;
+/**
+ * Owns the current Lab. A Lab is single-use; after a session ends, the next `start` gets a fresh one.
+ * Adapters may also force options (e.g. headless for a benchmark) that callers cannot override.
+ */
+export class SessionHost {
+    options;
+    forced;
+    current;
+    /**
+     * Set by an adapter that serves the live dashboard. Start and status results carry this URL, which is
+     * view-only: control (pause, takeover, stop) needs the person's URL from `agentlab ui`.
+     */
+    dashboardUrl;
+    /** A person stopped the session from the dashboard: no new session starts in this process. */
+    halted;
+    constructor(options, forced = {}) {
+        this.options = options;
+        this.forced = forced;
+        this.current = new Lab(options);
+    }
+    get lab() {
+        return this.current;
+    }
+    /**
+     * A person's supervision request (from the dashboard). After a stop or emergency stop this process
+     * starts no further session, so an agent cannot simply start again behind the person's back.
+     */
+    supervise(op, by = 'dashboard') {
+        const state = this.current.supervise(op, by);
+        if (op === 'stop' || op === 'emergency-stop')
+            this.halted = stopReason(op, by);
+        return state;
+    }
+    /** A Lab ready for `start`: the current one if unused, otherwise a new one once the old has ended. */
+    forStart() {
+        if (this.halted) {
+            throw new LabError('session_stopped', `Not starting: the previous session was ${this.halted}`, {
+                hint: 'Ask the user before continuing; they can restart the MCP server or the CLI session themselves.',
+            });
+        }
+        const s = this.current.status();
+        if (s.session && !s.active)
+            this.current = new Lab(this.options);
+        return this.current;
+    }
+}
+const schema = (properties, required = []) => ({ type: 'object', properties, ...(required.length ? { required } : {}), additionalProperties: false });
+const target = {
+    ref: { type: 'string', description: 'Session ref from the latest observation, e.g. e12' },
+    role: { type: 'string', description: 'Role, used with name when no ref is given' },
+    name: { type: 'string', description: 'Exact accessible name, used when no ref is given' },
+};
+const optionalTarget = {
+    ref: { type: 'string', description: 'Session ref from the latest observation (optional)' },
+    role: { type: 'string', description: 'Role, used with name when no ref is given' },
+    name: { type: 'string', description: 'Exact accessible name, used when no ref is given' },
+};
+const DIRECTIONS = ['up', 'down', 'left', 'right'];
+/**
+ * Run one action through the Lab. A role+name target is resolved against the latest observation
+ * (never guessed). `targeted` actions need a target; others (press, scroll, swipe…) may omit it.
+ */
+async function act(host, action, args, targeted = true) {
+    const lab = host.lab;
+    // Refused before the target is resolved, so a paused or taken-over session says so instead of not_found.
+    lab.admit(action, 'act');
+    let ref = args.ref;
+    if (!ref && args.name !== undefined)
+        ref = lab.findRef({ role: args.role, name: args.name });
+    if (!ref && targeted)
+        throw new LabError('invalid_request', `${action} needs a ref, or a name (optionally with role)`);
+    const request = {
+        action, ...(ref ? { ref } : {}),
+        ...pick(args, ['value', 'key', 'values', 'amount', 'toRef', 'dx', 'dy', 'files', 'tab', 'path']),
+        ...(args.direction ? { direction: args.direction } : {}),
+    };
+    const result = await lab.act(request);
+    return { result: result, text: formatAction(result) };
+}
+function pick(args, keys) {
+    return Object.fromEntries(keys.filter((k) => args[k] !== undefined).map((k) => [k, args[k]]));
+}
+const action = (name, description, properties, required = [], targeted = true) => ({
+    name, description, surfaces: ['cli', 'mcp'], kind: 'act', inputSchema: schema(properties, required), run: (host, args) => act(host, name, args, targeted),
+});
+export const COMMANDS = [
+    {
+        name: 'start',
+        kind: 'act',
+        description: 'Start or reuse the project web server from its agentlab.json profile, open a Chromium session with the device profile, and return the first observation.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({
+            project: { type: 'string', description: 'Project directory or path to agentlab.json' },
+            device: { type: 'string', description: 'Device profile id (default: from the profile)', maxLength: 100 },
+            headed: { type: 'boolean', description: 'Open a visible browser window (default false: watch in the dashboard instead)' },
+            slowMoMs: { type: 'number', description: 'Delay each browser operation, for watching', minimum: 0, maximum: 10_000 },
+            auth: { type: 'string', enum: ['auto', 'saved', 'fresh'], description: 'Saved sign-in state: auto (default: use it if saved), saved (require it), fresh (signed-out session)' },
+            trace: { type: 'boolean', description: 'Record a Playwright trace so a failure bundle can include a sanitized copy (default false)' },
+        }, ['project']),
+        async run(host, args) {
+            const result = await host.forStart().start({
+                project: args.project,
+                device: args.device,
+                // `mcp --headed` (forced.headless === false) shows the window unless the caller says otherwise.
+                headed: host.forced.headless ? false : (args.headed ?? (host.forced.headless === false ? true : undefined)),
+                slowMoMs: args.slowMoMs,
+                auth: args.auth,
+                trace: args.trace,
+            });
+            const url = host.dashboardUrl?.();
+            return {
+                result: { ...result, ...(url ? { dashboard: { url } } : {}) },
+                text: formatStart(result) + (url ? `\ndashboard: ${url}  (live viewport, timeline and findings for a person watching)` : ''),
+            };
+        },
+    },
+    {
+        name: 'observe',
+        kind: 'observe',
+        description: 'Return the compact state: route, headings, open dialog, visible interactive controls with session refs, page messages, layout flags, finding count, and console/network counts.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({ limit: { type: 'number', description: 'Maximum controls to return (default 40)', minimum: 1, maximum: 500 } }),
+        async run(host, args) {
+            const result = await host.lab.observe({ limit: args.limit });
+            return { result: result, text: formatObservation(result) };
+        },
+    },
+    {
+        name: 'click',
+        kind: 'act',
+        description: 'Tap (touch profiles) or click a control from the latest observation, by ref or unambiguous role+name. Verifies the event reached the control, waits for the UI to settle, and returns what changed plus any new usability findings.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({ ...target }),
+        run: (host, args) => act(host, 'click', args),
+    },
+    {
+        name: 'fill',
+        kind: 'act',
+        description: 'Replace the text of a text field from the latest observation, by ref or unambiguous role+name, then return what changed.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({ ...target, value: { type: 'string', description: 'Text to enter', maxLength: 20_000 } }, ['value']),
+        run: (host, args) => act(host, 'fill', args),
+    },
+    {
+        name: 'inspect',
+        kind: 'read',
+        description: 'Usability findings recorded in this session (layout overflow, clipped controls, controls only reachable by a sideways pan) with measured evidence and reproduction steps. Pass id for one finding, or ref for a control and its findings.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({
+            id: { type: 'string', description: 'Finding id, e.g. F2' },
+            ref: { type: 'string', description: 'Control ref from the latest observation' },
+        }),
+        async run(host, args) {
+            const result = host.lab.inspect({ id: args.id, ref: args.ref });
+            return { result: result, text: formatInspect(result) };
+        },
+    },
+    {
+        name: 'sweep',
+        kind: 'act',
+        description: 'Responsive sweep: load a route (default: the current one) at 320, 390, 768 and 1440 CSS px, one isolated browser context per width with the session\'s cookies and storage, and check layout (heuristic) and whether each control can be reached without a sideways pan or an obstruction (confirmed). Returns per-width results, findings and a report path; the session page is untouched.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({
+            route: { type: 'string', description: 'Path to sweep, e.g. /app/discover (default: current route)' },
+            devices: { type: 'string', description: `Comma-separated device ids (default: ${SWEEP_DEVICES.join(',')})` },
+        }),
+        async run(host, args) {
+            const devices = typeof args.devices === 'string' ? args.devices.split(',').map((d) => d.trim()).filter(Boolean) : undefined;
+            const result = await host.lab.sweep({ route: args.route, devices });
+            return { result: result, text: formatSweep(result) };
+        },
+    },
+    {
+        name: 'scan',
+        kind: 'act',
+        description: 'Stateful responsive scan: run the project\'s declared scenarios (agentlab.json scan.scenarios: a route, setup steps such as opening a drawer or a dialog, devices and checks) or one route as loaded, each device in its own isolated browser context, optionally exploring menus, disclosures, tabs and dialogs that are safe to open. Checks layout, clipping, fixed-bar collisions, dialog overflow, tap targets (WCAG 2.2), label wrapping between nearby widths and layout shifts. Returns the verdict, problem groups (inspect ids for details) and HTML/JSON report paths; the session page is untouched.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({
+            scenarios: { type: 'string', description: 'Comma-separated scenario names (default: all declared)' },
+            route: { type: 'string', description: 'Scan this route as loaded instead of the declared scenarios' },
+            devices: { type: 'string', description: 'Comma-separated device ids, overriding the scenarios\' devices' },
+            explore: { type: 'boolean', description: 'Explore safe state-opening controls (default: the profile\'s scan.explore.enabled)' },
+        }),
+        async run(host, args) {
+            const list = (v) => typeof v === 'string' ? v.split(',').map((d) => d.trim()).filter(Boolean) : undefined;
+            const result = await host.lab.scan({
+                scenarios: list(args.scenarios), devices: list(args.devices), route: args.route, explore: args.explore,
+            });
+            return { result: scanSummary(result), text: formatScan(result) };
+        },
+    },
+    {
+        name: 'bundle',
+        kind: 'read',
+        description: 'Write a failure bundle for the session so far: the action log (replayable by `agentlab replay`), recent observations, findings, console and network failures, evidence frames and, when the session records a trace, a sanitized trace. Secrets are removed. Returns the bundle\'s id, folder, files and counts, never its contents.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({ note: { type: 'string', description: 'Why the bundle is being written', maxLength: 500 } }),
+        async run(host, args) {
+            const r = await host.lab.bundle({ reason: args.note ?? 'requested' });
+            const c = r.counts;
+            const trace = r.trace === 'included' ? ', sanitized trace' : typeof r.trace === 'object' ? `, trace left out (${r.trace.dropped})` : '';
+            return {
+                result: { id: r.id, dir: r.dir, files: r.files, counts: c, trace: r.trace },
+                text: `bundle ${r.id} → ${r.dir}\n${c.actions} actions, ${c.observations} observations, ${c.findings} findings, ${c.consoleErrors} console errors, ${c.failedRequests} failed requests, ${c.frames} frames${trace}\nreplay: agentlab replay ${r.dir}`,
+            };
+        },
+    },
+    {
+        name: 'status',
+        kind: 'read',
+        description: 'Report whether a session is active, its device, server ownership and current route.',
+        surfaces: ['cli'],
+        inputSchema: schema({}),
+        async run(host) {
+            const s = host.lab.status();
+            const url = host.dashboardUrl?.();
+            const text = (s.session
+                ? `session ${s.session.id} ${s.active ? 'active' : `ended (${s.endedReason})`}  device ${s.session.device.id}  route ${s.route ?? '?'}  gen ${s.gen}  server ${s.server?.url} (${s.server?.owned ? 'owned' : 'reused'})`
+                : 'no session') + (url ? `\ndashboard: ${url}` : '');
+            return { result: { ...s, ...(url ? { dashboard: { url } } : {}) }, text };
+        },
+    },
+    {
+        name: 'stop',
+        kind: 'act',
+        description: 'Close the browser and stop the web server only if this session started it. Findings remain in the run directory.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({}),
+        async run(host, _args, surface) {
+            // From the terminal, stop is the owner's safety operation: it goes through even while a person has
+            // paused or taken over (the daemon socket is owner-only). An agent's MCP stop still needs control.
+            if (surface === 'cli' && host.lab.control.mode !== 'agent')
+                return stopAsOwner(host);
+            host.lab.admit('stop', 'act');
+            const result = await host.lab.close('requested');
+            return { result: result, text: formatClose(result) };
+        },
+    },
+    action('press', 'Press a key or chord (Enter, Escape, Tab, ArrowDown, Shift+Tab, Control+a) on a control (focused first) or on whatever has focus. Keys typed into password fields are masked in logs.', { key: { type: 'string', description: 'Key name or chord', maxLength: 64 }, ...optionalTarget }, ['key'], false),
+    action('select', 'Choose options in a native <select> by label or value, then return what changed.', { ...target, values: { type: 'array', items: { type: 'string', maxLength: 1000 }, minItems: 1, maxItems: 100, description: 'Option labels or values' } }, ['values']),
+    action('check', 'Check a checkbox, radio button or switch with a verified tap; a no-op if it is already checked. Confirms the state changed.', { ...target }),
+    action('uncheck', 'Uncheck a checkbox or switch with a verified tap; a no-op if it is already unchecked.', { ...target }),
+    action('scroll', 'Scroll the page, or the scrollable region containing a control, in a direction (down = reveal what is below), or bring a control into view when no direction is given. Reports how far it actually moved.', { direction: { type: 'string', enum: DIRECTIONS, description: 'Where to look next' }, amount: { type: 'number', description: 'CSS px (default 80% of the view)', minimum: 1, maximum: 100_000 }, ...optionalTarget }, [], false),
+    action('swipe', 'Touch swipe (the finger moves in this direction) from a control or the centre of the view, as real touch input. Needs a touch device profile.', { direction: { type: 'string', enum: DIRECTIONS, description: 'Finger movement' }, amount: { type: 'number', description: 'CSS px (default 60% of the view)', minimum: 1, maximum: 100_000 }, ...optionalTarget }, ['direction'], false),
+    action('back', 'Go back in the active tab\'s history, then return what changed.', {}, [], false),
+    action('forward', 'Go forward in the active tab\'s history, then return what changed.', {}, [], false),
+    action('hover', 'Move the pointer over a control (after scrolling it into view) and return what appeared.', { ...target }),
+    action('upload', 'Give files to a file input, or to a button that opens a file chooser. Files are project-relative and must be inside the profile\'s uploads.allow directories.', { ...target, files: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 20, description: 'Project-relative file paths' } }, ['files']),
+    action('drag', 'Drag a control onto another control (toRef) or by an offset (dx, dy CSS px), with a real pointer press, move and release.', { ...target, toRef: { type: 'string', description: 'Ref of the drop target' }, dx: { type: 'number', description: 'Horizontal offset', minimum: -100_000, maximum: 100_000 }, dy: { type: 'number', description: 'Vertical offset', minimum: -100_000, maximum: 100_000 } }),
+    {
+        name: 'tabs',
+        kind: 'read',
+        description: 'List open tabs (pop-ups and target=_blank links become tabs); the active one is observed and acted on.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({}),
+        async run(host) {
+            const tabs = await host.lab.tabList();
+            return { result: { tabs }, text: formatTabs(tabs) };
+        },
+    },
+    action('open_tab', 'Open a new tab at a path on the app\'s origin and switch to it.', { path: { type: 'string', description: 'Path, e.g. /help' } }, ['path'], false),
+    action('switch_tab', 'Make another tab the active one and observe it.', { tab: { type: 'string', description: 'Tab id, e.g. t2' } }, ['tab'], false),
+    action('close_tab', 'Close a tab (default: the active one) and switch to its opener.', { tab: { type: 'string', description: 'Tab id (default: active)' } }, [], false),
+    {
+        name: 'auth_save',
+        kind: 'act',
+        description: 'Save this session\'s sign-in state (cookies and localStorage) so later sessions start signed in. Written owner-only to a git-ignored file; the state itself is never returned.',
+        surfaces: ['cli', 'mcp'],
+        inputSchema: schema({}),
+        async run(host) {
+            const r = await host.lab.saveAuth();
+            return { result: r, text: `saved sign-in state: ${r.cookies} cookies, ${r.origins} origins with storage → ${r.file} (owner-only; start with auth "fresh" to ignore it)` };
+        },
+    },
+];
+export function getCommand(name, surface = 'cli') {
+    const cmd = COMMANDS.find((c) => c.name === name && c.surfaces.includes(surface));
+    if (!cmd) {
+        throw new LabError('invalid_request', `Unknown command "${name}"`, {
+            hint: `Commands: ${COMMANDS.filter((c) => c.surfaces.includes(surface)).map((c) => c.name).join(', ')}`,
+        });
+    }
+    return cmd;
+}
+/** Validate arguments against a command's flat schema. Returns a cleaned copy. */
+export function validateArgs(cmd, args) {
+    const input = (typeof args === 'object' && args !== null && !Array.isArray(args) ? args : {});
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined)
+            continue;
+        const prop = cmd.inputSchema.properties[key];
+        if (!prop)
+            throw new LabError('invalid_request', `${cmd.name}: unknown argument "${key}"`);
+        const bad = (why) => new LabError('invalid_request', `${cmd.name}: "${key}" ${why}`);
+        if (prop.type === 'array') {
+            if (!Array.isArray(value) || !value.every((v) => typeof v === prop.items.type))
+                throw bad(`must be a list of ${prop.items.type}s`);
+            if (prop.minItems && value.length < prop.minItems)
+                throw bad(`needs at least ${prop.minItems} item(s)`);
+            const maxItems = prop.maxItems ?? DEFAULT_MAX_ITEMS;
+            if (value.length > maxItems)
+                throw bad(`takes at most ${maxItems} items`);
+            const maxLength = prop.items.maxLength ?? DEFAULT_MAX_LENGTH;
+            if (value.some((v) => v.length > maxLength))
+                throw bad(`items must be at most ${maxLength} characters`);
+        }
+        else {
+            if (typeof value !== prop.type)
+                throw bad(`must be a ${prop.type}`);
+            if (prop.type === 'string') {
+                if (prop.enum && !prop.enum.includes(value))
+                    throw bad(`must be one of ${prop.enum.join(', ')}`);
+                const maxLength = prop.maxLength ?? DEFAULT_MAX_LENGTH;
+                if (value.length > maxLength)
+                    throw bad(`must be at most ${maxLength} characters`);
+            }
+            if (prop.type === 'number') {
+                if (!Number.isFinite(value))
+                    throw bad('must be a finite number');
+                if (prop.minimum !== undefined && value < prop.minimum)
+                    throw bad(`must be at least ${prop.minimum}`);
+                if (prop.maximum !== undefined && value > prop.maximum)
+                    throw bad(`must be at most ${prop.maximum}`);
+            }
+        }
+        out[key] = value;
+    }
+    for (const key of cmd.inputSchema.required ?? []) {
+        if (out[key] === undefined)
+            throw new LabError('invalid_request', `${cmd.name}: "${key}" is required`);
+    }
+    return out;
+}
+/**
+ * `agentlab stop` while the session is paused, held by a person, or already stopping: recorded as a stop
+ * from the terminal. The command in flight (if any) finishes first, as with the dashboard's stop.
+ */
+async function stopAsOwner(host) {
+    const lab = host.lab;
+    if (lab.status().active && lab.control.mode !== 'stopping' && lab.control.mode !== 'stopped')
+        host.supervise('stop', 'terminal');
+    await lab.control.whenIdle();
+    const result = await lab.close(stopReason('stop', 'terminal'));
+    return { result: result, text: formatClose(result) };
+}
+/** Run a command by name for an adapter: validation, dispatch and error normalisation in one place. */
+export async function dispatch(host, surface, name, args) {
+    try {
+        const cmd = getCommand(name, surface);
+        return { ok: true, output: await cmd.run(host, validateArgs(cmd, args), surface) };
+    }
+    catch (err) {
+        return { ok: false, error: LabError.from(err).toJSON() };
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/core/control.js

@@ -0,0 +1,217 @@
+import { LabError } from './schema.js';
+export const CONTROL_OPS = ['pause', 'pause-next', 'resume', 'takeover', 'return', 'stop', 'emergency-stop'];
+/**
+ * How a supervision stop is recorded. A stop from the terminal is the owner channel, but anything with a
+ * shell as this user can issue it, so it is labelled by where it came from rather than as a person's.
+ */
+export function stopReason(op, by = 'dashboard') {
+    if (by === 'terminal')
+        return op === 'stop' ? 'stopped from the terminal' : 'emergency stop from the terminal';
+    return `${op === 'stop' ? 'stopped' : 'emergency stop'} by a person (${by})`;
+}
+const iso = () => new Date().toISOString();
+export class Supervisor {
+    s = { mode: 'agent', interrupt: false, since: iso(), observeRequired: false, humanInteractions: 0 };
+    listeners = new Set();
+    waiters = [];
+    idleWaiters = [];
+    get state() {
+        return structuredClone(this.s);
+    }
+    get mode() {
+        return this.s.mode;
+    }
+    /** A person is watching or holding the page: human input is recorded only then. */
+    get recordingHuman() {
+        return this.s.mode === 'paused' || this.s.mode === 'human';
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => { this.listeners.delete(fn); };
+    }
+    /**
+     * Apply a person's request. Throws `invalid_control` for a request that makes no sense in the current
+     * mode (e.g. resume while the agent already has control), so the dashboard can say why.
+     */
+    request(op, by = 'dashboard') {
+        const s = this.s;
+        const busy = !!s.busy;
+        const invalid = (why) => new LabError('invalid_control', `Cannot ${op}: ${why}`, { details: { mode: s.mode } });
+        if (s.mode === 'stopped')
+            throw invalid('the session has stopped');
+        switch (op) {
+            case 'pause':
+            case 'pause-next': {
+                const interrupt = op === 'pause';
+                if (s.mode === 'agent')
+                    this.set(busy ? { mode: 'pausing', pending: 'paused', interrupt } : { mode: 'paused', interrupt: false }, by);
+                else if (s.mode === 'pausing' && s.pending === 'paused')
+                    this.set({ mode: 'pausing', pending: 'paused', interrupt: s.interrupt || interrupt }, by);
+                else
+                    throw invalid(`the session is ${describe(s)}`);
+                break;
+            }
+            case 'takeover':
+                if (s.mode === 'agent' || s.mode === 'pausing' || s.mode === 'paused') {
+                    this.set(busy ? { mode: 'pausing', pending: 'human', interrupt: true } : { mode: 'human', interrupt: false }, by);
+                }
+                else
+                    throw invalid(`the session is ${describe(s)}`);
+                break;
+            case 'resume':
+                if (s.mode === 'paused' || (s.mode === 'pausing' && s.pending === 'paused')) {
+                    this.set({ mode: 'agent', interrupt: false, observeRequired: s.observeRequired || s.humanInteractions > 0 }, by);
+                }
+                else
+                    throw invalid(s.mode === 'human' ? 'a person has control; use return to hand it back' : `the session is ${describe(s)}`);
+                break;
+            case 'return':
+                if (s.mode === 'human' || (s.mode === 'pausing' && s.pending === 'human')) {
+                    // Whatever the person did, refs from before are no longer trustworthy.
+                    this.set({ mode: 'agent', interrupt: false, observeRequired: s.mode === 'human' || s.humanInteractions > 0 }, by);
+                }
+                else
+                    throw invalid(`the session is ${describe(s)}`);
+                break;
+            case 'stop':
+                if (s.mode === 'stopping')
+                    throw invalid('it is already stopping');
+                this.set(busy ? { mode: 'stopping', pending: 'stop', interrupt: true } : { mode: 'stopped', interrupt: true }, by);
+                break;
+            case 'emergency-stop':
+                this.set({ mode: 'stopped', interrupt: true }, by);
+                break;
+        }
+        this.emit(op, by);
+        return this.state;
+    }
+    /**
+     * Refuse an agent command that may not run now. Read-only commands always run; observe runs unless a
+     * person holds the page; anything that acts needs agent control and, after a hand-back, a fresh observe.
+     */
+    admit(command, kind) {
+        if (kind === 'read')
+            return;
+        const s = this.s;
+        const details = { control: { mode: s.mode, ...(s.by ? { by: s.by } : {}), since: s.since } };
+        if (s.mode === 'stopping' || s.mode === 'stopped') {
+            throw new LabError('session_stopped', `${command} refused: a person stopped this session`, {
+                hint: 'Nothing was run. The session is closing or closed; ask the user before starting another.', details
+            });
+        }
+        if (s.mode === 'human' || (s.mode === 'pausing' && s.pending === 'human')) {
+            throw new LabError('human_control', `${command} refused: a person has taken control of the browser`, {
+                hint: 'Nothing was run and nothing is queued. Wait for the person to hand control back, then observe (refs from before will be stale).', details,
+            });
+        }
+        if (kind === 'observe')
+            return;
+        if (s.mode === 'paused' || s.mode === 'pausing') {
+            throw new LabError('session_paused', `${command} refused: a person paused the session`, {
+                hint: 'Nothing was run and nothing is queued. observe, inspect and status still work; retry the action after the person resumes.', details,
+            });
+        }
+        // Stopping acts on no ref, so stale refs do not matter: after a hand-back it needs no fresh observe.
+        if (s.observeRequired && command !== 'stop') {
+            throw new LabError('observation_required', `${command} refused: a person used the browser since the last observation`, {
+                hint: 'Refs issued before are stale. Run observe, then act on fresh refs.', details,
+            });
+        }
+    }
+    /** The agent observed after a hand-back: acting is allowed again. */
+    observed() {
+        if (this.s.mode !== 'agent' || !this.s.observeRequired)
+            return;
+        this.set({ mode: 'agent', interrupt: false, observeRequired: false, humanInteractions: 0 }, this.s.by);
+        this.emit('observed', this.s.by);
+    }
+    /** A person interacted with the page while it was paused or under their control. */
+    humanInteraction() {
+        if (this.recordingHuman)
+            this.s.humanInteractions++;
+    }
+    /** A session operation began. Nested operations (a scan inside a flow step) keep the outer label. */
+    begin(command) {
+        this.s.busy ??= { command, since: iso() };
+    }
+    /** The operation in flight finished: a pending pause, takeover or stop takes effect now. */
+    end() {
+        if (!this.s.busy)
+            return;
+        delete this.s.busy;
+        const s = this.s;
+        if (s.mode === 'pausing')
+            this.set({ mode: s.pending === 'human' ? 'human' : 'paused', interrupt: false }, s.by);
+        else if (s.mode === 'stopping')
+            this.set({ mode: 'stopped', interrupt: true }, s.by);
+        else {
+            this.flushIdle();
+            return;
+        }
+        this.emit('settled', s.by);
+        this.flushIdle();
+    }
+    get busy() {
+        return !!this.s.busy;
+    }
+    /** Resolves when no operation is in flight. */
+    whenIdle() {
+        if (!this.s.busy)
+            return Promise.resolve();
+        return new Promise((r) => this.idleWaiters.push(r));
+    }
+    /** For long commands between units of work: true when they should stop now (pause, takeover or stop). */
+    shouldInterrupt() {
+        return this.s.interrupt && (this.s.mode === 'pausing' || this.s.mode === 'stopping' || this.s.mode === 'stopped');
+    }
+    /**
+     * For a scripted runner (a flow) that has no one to return an error to: wait until the agent has
+     * control. Rejects with session_stopped when a person stops the session.
+     */
+    waitForTurn() {
+        const s = this.s.mode;
+        if (s === 'agent')
+            return Promise.resolve();
+        if (s === 'stopping' || s === 'stopped')
+            return Promise.reject(new LabError('session_stopped', 'A person stopped this session'));
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+    set(next, by) {
+        const keep = { observeRequired: this.s.observeRequired, humanInteractions: this.s.humanInteractions, ...(this.s.busy ? { busy: this.s.busy } : {}) };
+        const modeChanged = next.mode !== this.s.mode;
+        this.s = { ...keep, ...next, ...(by ? { by } : {}), since: modeChanged ? iso() : this.s.since };
+        if (next.mode === 'agent' && modeChanged)
+            this.s.humanInteractions = 0;
+        if (!next.pending)
+            delete this.s.pending;
+        this.wake();
+    }
+    wake() {
+        const m = this.s.mode;
+        if (m === 'agent') {
+            for (const w of this.waiters.splice(0))
+                w.resolve();
+        }
+        else if (m === 'stopping' || m === 'stopped') {
+            for (const w of this.waiters.splice(0))
+                w.reject(new LabError('session_stopped', 'A person stopped this session'));
+        }
+    }
+    flushIdle() {
+        for (const r of this.idleWaiters.splice(0))
+            r();
+    }
+    emit(op, by) {
+        const change = { op, ...(by ? { by } : {}), state: this.state };
+        for (const fn of this.listeners)
+            fn(change);
+    }
+}
+function describe(s) {
+    if (s.mode === 'pausing')
+        return s.pending === 'human' ? 'waiting to hand control to a person' : 'already pausing';
+    if (s.mode === 'human')
+        return 'under a person\'s control';
+    return s.mode;
+}
+//# sourceMappingURL=control.js.map