@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/browser-panel-tool.js

@@ -0,0 +1,227 @@
+import { randomUUID } from 'node:crypto';
+import { browserViewUrl } from './browser-view.js';
+import { authorize } from './tools.js';
+import { browserEventArguments, IMAGE_LIMIT, PENDING_IMAGE_LIMIT, reserveBrowserImage } from './browser-session.js';
+const OPERATIONS = ['open', 'navigate', 'back', 'forward', 'refresh', 'tabs', 'activate', 'close_tab', 'snapshot', 'click', 'fill', 'press', 'scroll', 'wait', 'screenshot'];
+const ARGUMENTS = ['operation', 'url', 'tabId', 'selector', 'value', 'key', 'button', 'deltaY'];
+function text(args, name, max = 2048) {
+    const value = args[name];
+    if (typeof value !== 'string' || !value || value.length > max)
+        throw new Error(`${name} must be a nonempty string of at most ${max} characters`);
+    return value;
+}
+/**
+ * Race a manager call that carries no signal of its own, so a cancelled run
+ * never awaits it forever. Failure ends the call; the shared panel browser,
+ * which the user may be watching, is left exactly as it is.
+ */
+function bound(signal, pending, timeoutMs, timeoutMessage) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); };
+        const fail = (error) => { if (settled)
+            return; settled = true; cleanup(); reject(error); };
+        const abort = () => fail(signal.reason);
+        const timer = setTimeout(() => fail(new Error(timeoutMessage)), timeoutMs);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        pending.then(value => { if (!settled) {
+            settled = true;
+            cleanup();
+            resolve(value);
+        } }, fail);
+    });
+}
+/** Validate one panel operation the same way wherever it enters: the tool, or the owning engine's relay RPC. */
+export function validatePanelArguments(args) {
+    const operation = text(args, 'operation', 20);
+    if (!OPERATIONS.includes(operation) || Object.keys(args).some(key => !ARGUMENTS.includes(key)))
+        throw new Error('Invalid browser panel operation or argument');
+    const url = ['open', 'navigate'].includes(operation) ? browserViewUrl(text(args, 'url')) : undefined;
+    if (args.button !== undefined && (operation !== 'click' || !['left', 'right', 'middle'].includes(args.button)))
+        throw new Error('button must be left, right or middle for click');
+    if (args.tabId !== undefined)
+        text(args, 'tabId', 64);
+    const selector = ['click', 'fill', 'wait'].includes(operation) || args.selector !== undefined ? text(args, 'selector', 1024) : undefined;
+    if (operation === 'fill' && (typeof args.value !== 'string' || args.value.length > 16000))
+        throw new Error('fill requires a string value of at most 16000 characters');
+    if (operation === 'press')
+        text(args, 'key', 80);
+    if (operation === 'scroll' && (!Number.isSafeInteger(args.deltaY) || Math.abs(args.deltaY) > 3000))
+        throw new Error('scroll requires an integer deltaY within ±3000');
+    const tabId = typeof args.tabId === 'string' ? args.tabId : undefined;
+    return {
+        operation, ...(url === undefined ? {} : { url }), ...(tabId === undefined ? {} : { tabId }),
+        ...(selector === undefined ? {} : { selector }),
+        ...(args.value === undefined ? {} : { value: args.value }),
+        ...(args.key === undefined ? {} : { key: args.key }),
+        ...(args.button === undefined ? {} : { button: args.button }),
+        ...(args.deltaY === undefined ? {} : { deltaY: args.deltaY }),
+    };
+}
+/**
+ * Execute one validated panel operation against the engine that owns the
+ * session's panel browser. Shared by the tool's local path (the engine that
+ * runs the agent also owns the panel) and by the `browser.panel.op` RPC an
+ * owning engine answers for a run engine relaying through the desktop.
+ */
+export async function runPanelOperation(views, sessionId, args, signal) {
+    const { operation, url, tabId, selector } = args;
+    if (operation === 'tabs')
+        return { result: panelTabsResult(views, sessionId) };
+    if (operation === 'screenshot') {
+        const shot = await views.agentScreenshot(sessionId, tabId, signal);
+        signal.throwIfAborted();
+        if (shot.data.length > IMAGE_LIMIT)
+            throw new Error('Screenshot exceeds the 512 KiB visual observation limit');
+        return { result: JSON.stringify({ sessionId, tabId: shot.tabId, screenshotId: randomUUID(), bytes: shot.data.length, width: shot.width, height: shot.height }), image: { mimeType: 'image/jpeg', data: shot.data.toString('base64') } };
+    }
+    if (operation === 'open') {
+        let opened;
+        // The open's deadline is its own cancellation: a launch or page creation that outlasts it must
+        // not select and navigate a tab the agent has already stopped waiting for and may have retried.
+        // The controller follows the run's signal as well, so a stop and a timeout end the same work.
+        const opening = new AbortController();
+        const follow = () => opening.abort(signal.reason);
+        signal.addEventListener('abort', follow, { once: true });
+        if (signal.aborted)
+            follow();
+        const pending = views.openTab(sessionId, url, opening.signal);
+        // The deadline may settle this call first; the creation it gave up on reports through the
+        // controller, not through a rejection nobody holds.
+        pending.catch(() => { });
+        try {
+            opened = await bound(opening.signal, pending, 35_000, 'Browser open exceeded the 35-second timeout.');
+        }
+        catch (error) {
+            opening.abort(error);
+            const message = error instanceof Error ? error.message : String(error);
+            if (/Browser runtime is not usable/.test(message))
+                throw new Error(`${message} Ask the user to open the Browser panel so its runtime can be installed, or use qa.browser_session if available.`);
+            throw error;
+        }
+        finally {
+            signal.removeEventListener('abort', follow);
+        }
+        return { result: await views.agentSnapshot(sessionId, opened.tabId, signal) };
+    }
+    if (operation === 'navigate')
+        await bound(signal, views.navigate(sessionId, url, tabId), 35_000, 'Browser navigate exceeded the 35-second timeout.');
+    else if (operation === 'back' || operation === 'forward' || operation === 'refresh')
+        await views.go(sessionId, operation, tabId);
+    else if (operation === 'activate') {
+        if (tabId === undefined)
+            throw new Error('activate requires a tabId');
+        await bound(signal, views.activateTab(sessionId, tabId), 10_000, 'Browser activate exceeded the 10-second timeout.');
+    }
+    else if (operation === 'close_tab') {
+        await bound(signal, views.closeTab(sessionId, tabId), 10_000, 'Browser close exceeded the 10-second timeout.');
+        return { result: panelTabsResult(views, sessionId) };
+    }
+    else if (operation === 'click')
+        await views.agentClick(sessionId, { selector: selector, button: args.button ?? 'left', tabId }, signal);
+    else if (operation === 'fill')
+        await views.agentFill(sessionId, { selector: selector, value: args.value, tabId }, signal);
+    else if (operation === 'press')
+        await views.agentPress(sessionId, { key: args.key, selector, tabId }, signal);
+    else if (operation === 'scroll')
+        await views.agentScroll(sessionId, { deltaY: args.deltaY, tabId }, signal);
+    else if (operation === 'wait')
+        await views.agentWait(sessionId, { selector: selector, tabId }, signal);
+    signal.throwIfAborted();
+    return { result: await views.agentSnapshot(sessionId, tabId, signal) };
+}
+/**
+ * The tab list in the shape every browser tool's persisted observations share
+ * (`{sessionId, tabs}` with per-tab `active`), so trajectory sanitization can
+ * validate it instead of discarding it as an unrecognized page payload.
+ */
+function panelTabsResult(views, sessionId) {
+    const summary = views.agentTabs(sessionId);
+    return JSON.stringify({ sessionId, tabs: summary.tabs.map(tab => ({ tabId: tab.id, active: tab.id === summary.activeTabId, url: tab.url, title: tab.title })) });
+}
+/**
+ * The agent's handle on the session's browser panel: the same tabs, cookies and
+ * login state the user sees and shares in the desktop's Browser panel. Created
+ * per run by the app-server: on the engine that owns the panel the operations
+ * run locally; on a task engine they relay through the desktop to the owning
+ * engine. Environments without a panel (the CLI) never create one, so the tool
+ * never appears there.
+ */
+export function createBrowserPanelTool(views, sessionId, relay) {
+    /** Captured screenshots awaiting the runtime's resultImages collection. */
+    const pending = new Map();
+    return {
+        name: 'browser.panel', family: 'browser', capability: 'browser', executionMode: 'sequential',
+        description: 'Drive the browser this session shows in its Browser panel: the visible browser the user shares, not an isolated one. Tabs, cookies and login state are shared with the user, and every action appears live in the panel, so prefer it whenever the user asks to use "the browser" or wants to watch, demonstrate or verify browsing (site logins, visual checks). open/navigate take an HTTP(S) url; every operation except tabs/screenshot answers with a snapshot whose observed CSS selectors drive click/fill/wait. tabId, from a snapshot or tabs, optionally targets one tab, otherwise the active tab. Operations: open, navigate, back, forward, refresh, tabs, activate, close_tab, snapshot, click, fill, press, scroll, wait, screenshot. screenshot returns a native image; at most 10 images and 2 MiB per agent tool batch. There is deliberately no whole-browser close: close individual tabs instead. Browser capability and normal approvals are required.',
+        parameters: { type: 'object', properties: {
+                operation: { type: 'string', enum: OPERATIONS },
+                url: { type: 'string', description: 'HTTP(S) target for open/navigate' },
+                tabId: { type: 'string', description: 'Observed tab id; required for activate, optional target for the rest (default the active tab)' },
+                selector: { type: 'string', description: 'Observed CSS selector for click/fill/wait; optional focus target for press' },
+                value: { type: 'string', description: 'Text for fill' },
+                key: { type: 'string', description: 'Playwright key name, e.g. Enter or ArrowUp' },
+                button: { type: 'string', enum: ['left', 'right', 'middle'], description: 'Mouse button for click; default left' },
+                deltaY: { type: 'integer', minimum: -3000, maximum: 3000, description: 'Scroll distance in pixels for scroll' },
+            }, required: ['operation'], additionalProperties: false },
+        eventOutput: output => {
+            // Host metadata only, in the exact envelopes trajectory sanitization
+            // recognizes (`{sessionId}` or `{sessionId, screenshotId}`); the page's
+            // text and the agent's inputs never enter persisted events.
+            try {
+                const data = JSON.parse(output);
+                return JSON.stringify({ sessionId, ...(data.screenshotId === undefined ? {} : { screenshotId: data.screenshotId }) });
+            }
+            catch {
+                return 'Browser panel observation (content omitted)';
+            }
+        },
+        resultImages: output => {
+            const image = pending.get(output);
+            pending.delete(output);
+            return image ? [image] : undefined;
+        },
+        execute: async (args, context) => {
+            // Validate before launching, relaying or asking for approval.
+            const validated = validatePanelArguments(args);
+            await authorize('browser.panel', browserEventArguments(args), context);
+            context.signal.throwIfAborted();
+            // One operation, whichever engine's browser executes it: the owning
+            // engine's answer, or this one's own manager when it owns the panel.
+            const run = relay
+                ? async () => {
+                    const answer = await relay(validated.operation, args, context.signal);
+                    if (answer.error)
+                        throw new Error(answer.error);
+                    if (answer.result === undefined)
+                        throw new Error('The panel browser relay returned no result');
+                    return { result: answer.result, ...(answer.image ? { image: answer.image } : {}) };
+                }
+                : () => runPanelOperation(views, sessionId, validated, context.signal);
+            if (validated.operation === 'screenshot') {
+                // The reservation is held on the engine whose agent asked for the image,
+                // whichever engine's browser captures it. An agent must consume its own
+                // pending observations; never silently evict another invocation's result.
+                if (pending.size >= PENDING_IMAGE_LIMIT)
+                    throw new Error('Consume pending screenshots before capturing another (maximum 10 per session)');
+                const reservation = reserveBrowserImage(context);
+                let committed = false;
+                try {
+                    const captured = await run();
+                    const bytes = Number.isSafeInteger(JSON.parse(captured.result).bytes) ? JSON.parse(captured.result).bytes : IMAGE_LIMIT;
+                    reservation.commit(bytes);
+                    committed = true;
+                    if (captured.image)
+                        pending.set(captured.result, captured.image);
+                    return captured.result;
+                }
+                finally {
+                    if (!committed)
+                        reservation.refund();
+                }
+            }
+            return (await run()).result;
+        },
+    };
+}

package/dist/src/browser-runner.d.ts

@@ -0,0 +1,16 @@
+import { type RunResult } from './runtime.js';
+import type { SavedSession } from './sessions.js';
+import type { RuntimeEvent } from './types.js';
+export interface BrowserTaskControl {
+    signal: AbortSignal;
+    steering: () => string[];
+    event: (event: RuntimeEvent) => Promise<void>;
+    ask: (kind: 'question' | 'approval', question: string, signal: AbortSignal, choices?: {
+        id: string;
+        label: string;
+    }[]) => Promise<string | undefined>;
+}
+/** Run a GUI conversation through the same graph and permission gates as the CLI. */
+export declare function runBrowserTask(session: SavedSession, task: string, control: BrowserTaskControl, options?: {
+    directory?: string;
+}): Promise<RunResult>;

package/dist/src/browser-runner.js

@@ -0,0 +1,302 @@
+import { randomUUID } from 'node:crypto';
+import { realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { configDirectory, loadConfig, resolveCodeIntelConfig, resolveConfiguredLimits } from './config.js';
+import { workspacePermissionKey } from './permissions.js';
+import { configuredGraphSelection, currentGraphSubject } from './graph-selection.js';
+import { getMembership, loadAccessibleGraph, PaidMembershipRequiredError } from './membership.js';
+import { FreeTierLimitError } from './graph-quota.js';
+import { GraphProviderUnavailableError } from './graph-provider-portability.js';
+import { checkGraphModelHealth, formatGraphHealthFailure } from './graph-health.js';
+import { validateGraph } from './graphs.js';
+import { validateValue } from './handoffs.js';
+import { createAdapter } from './providers.js';
+import { refreshModelContext, resolveModelContext } from './model-metadata.js';
+import { runGraph } from './runtime.js';
+import { createTools } from './tools.js';
+import { loadWorkspaceInstructions } from './workspace-instructions.js';
+import { QA_SYSTEM_GUIDANCE } from './qa/index.js';
+import { extensionSnapshot } from './extensions.js';
+import { connectMcpServers } from './mcp.js';
+import { hostedDecisionPolicy } from './decision/hostedPolicy.js';
+import { CodeIntelligenceManager } from './code-intelligence/CodeIntelligenceManager.js';
+import { LocalToolMemory } from './memory/LocalToolMemory.js';
+import { TodoStore } from './todos.js';
+import { RunControl } from './run-control.js';
+import { createSessionTrajectory } from './trajectory.js';
+import { describeTool } from './transcript.js';
+import { disposeBrowserSessions } from './browser-session.js';
+import { configuredSurface, createRunHandle, drainTelemetry, graphShape, reportRunFinished, reportRunStarted } from './telemetry/surface.js';
+import { createRunTelemetry, recordModelUse } from './telemetry/capture.js';
+/** Run a GUI conversation through the same graph and permission gates as the CLI. */
+export async function runBrowserTask(session, task, control, options = {}) {
+    const clarificationCancellation = new AbortController();
+    const signal = AbortSignal.any([control.signal, clarificationCancellation.signal]);
+    signal.throwIfAborted();
+    // The server may run against a home other than the process default (an embedded engine), and
+    // this run's lifecycle events must be judged and stored in that same home: a Paid opt-out there
+    // would otherwise be answered by the default home's state.
+    const directory = options.directory ?? configDirectory();
+    // A browser-owned run runs outside the CLI and app-server finalizers, so it owns its own
+    // lifecycle pair; without it these runs are absent from every lifecycle metric. The subject is
+    // resolved once here so the gate answers for the account that owns the run, not the newest
+    // cached account on a shared installation.
+    const accountSubject = await currentGraphSubject().catch(() => undefined);
+    const telemetryRunId = randomUUID();
+    const startedAt = new Date().toISOString();
+    const telemetrySurface = { home: directory, surface: configuredSurface('desktop'), ...(accountSubject === undefined ? {} : { subject: accountSubject }) };
+    // Allocated and started before the setup below: the browser server has already persisted the
+    // request, so a failure while resolving the workspace, loading the configuration or opening the
+    // trajectory is still a run that began and ended inside this task. The dimensions start as the
+    // defaults and are replaced once the configuration is loaded.
+    const telemetryHandle = createRunHandle(telemetryRunId, startedAt, {
+        graphId: 'default', nodes: 0, subagents: false, permissionMode: 'ask-for-approval',
+        jevEnabled: true, decisionRouting: 'off',
+    }, session.workspace);
+    let telemetryStarted = false;
+    const beginTelemetry = async () => {
+        if (telemetryStarted)
+            return;
+        telemetryStarted = true;
+        await reportRunStarted(telemetrySurface, telemetryHandle);
+    };
+    // The start is queued once the graph and settings are known, so the serialized start carries the
+    // dimensions its finish will repeat. A failure during setup still reports a matched pair, using
+    // whatever dimensions were resolved before the failure.
+    let workspace;
+    let config;
+    let selected;
+    let trajectory;
+    try {
+        workspace = await realpath(session.workspace);
+        config = await loadConfig(directory);
+        const found = config.providers.find(provider => provider.id === config.provider);
+        if (!found)
+            throw new Error('Add a provider with /providers in the CLI before starting a browser run.');
+        selected = found;
+        Object.assign(telemetryHandle.dimensions, {
+            graphId: config.graph ?? 'default',
+            permissionMode: config.workspacePermissions?.[workspacePermissionKey(workspace)] ?? 'ask-for-approval',
+            jevEnabled: config.jevEnabled !== false, decisionRouting: config.decisions?.mode ?? 'off',
+        });
+        telemetryHandle.workspace = workspace;
+        // The engine log lives in this home's `trajectories`, under the session's id, as the desktop's does:
+        // that is where the session's trajectory reader looks. Left to its default, the writer would put it
+        // beside the installation instead, where no reader finds it.
+        const trajectoryDirectory = join(directory, 'trajectories');
+        const reopened = await stat(join(trajectoryDirectory, `${session.id}.jsonl`)).then(() => true, () => false);
+        trajectory = await createSessionTrajectory({ sessionId: session.id, directory: trajectoryDirectory, reopened,
+            secrets: config.providers.flatMap(provider => [provider.apiKey, provider.apiKeyEnv ? process.env[provider.apiKeyEnv] : undefined].filter((value) => !!value)),
+            meta: { workspace, browser: true } });
+    }
+    catch (error) {
+        // The browser server already recorded the accepted request, so this is a run that started and
+        // ended, not one that never happened.
+        const message = error instanceof Error ? error.message : String(error);
+        await beginTelemetry().catch(() => { });
+        await reportRunFinished(telemetrySurface, telemetryHandle, {
+            status: signal.aborted ? 'cancelled' : 'infrastructure_error', reason: message
+        }).catch(() => { });
+        throw error;
+    }
+    const permissions = config.workspacePermissions?.[workspacePermissionKey(workspace)] ?? 'ask-for-approval';
+    const runControl = new RunControl();
+    runControl.permissions = permissions;
+    runControl.yolo = permissions === 'full-access';
+    const runId = randomUUID();
+    const browserSessionOwner = {};
+    const onEvent = async (event) => {
+        const identified = { ...event, data: { ...event.data, conversationId: session.id, runId: event.data.runId ?? runId } };
+        await trajectory.recordEvent(identified);
+        await control.event(trajectory.sanitize(identified));
+    };
+    // Reuse the run's sanitizer: adapter recording learns private browser fills
+    // that the browser server's separate trajectory has never observed.
+    const ask = (kind, question, questionSignal, choices) => control.ask(kind, trajectory.sanitize(question), questionSignal, choices?.map(choice => ({ ...choice, label: trajectory.sanitize(choice.label) })));
+    const notice = (message) => onEvent({ type: 'browser.notice', time: new Date().toISOString(), data: { message } });
+    const context = {
+        workspace, signal, userSignal: signal, runControl, browserSessionOwner,
+        permissions, yolo: permissions === 'full-access', approvalMode: 'interactive',
+        onApprovalEvent: (type, data) => onEvent({ type, time: new Date().toISOString(), data }),
+        approve: async (name, args, approvalSignal) => (await ask('approval', `Approve ${describeTool(name, args)}?\n\n${JSON.stringify(args, null, 2)}`, approvalSignal, [{ id: 'deny', label: 'Deny' }, { id: 'approve', label: 'Approve' }])) === 'approve',
+        askUser: async (question, questionSignal, choices) => {
+            const declined = () => { clarificationCancellation.abort(new Error('The user cancelled clarification.')); return undefined; };
+            if (!choices?.length) {
+                const answer = await ask('question', question, questionSignal);
+                return answer?.trim() && answer.trim().toLowerCase() !== '/cancel' ? answer : declined();
+            }
+            const answer = await ask('question', question, questionSignal, [
+                ...choices.map((label, index) => ({ id: `answer:${index}`, label })),
+                { id: 'custom', label: 'Other (Enter yourself)' },
+                { id: 'cancel', label: 'Cancel this task' },
+            ]);
+            if (answer === undefined || answer === 'cancel' || answer.trim().toLowerCase() === '/cancel')
+                return declined();
+            if (answer === 'custom') {
+                const custom = await ask('question', `${question}\n\nYour answer`, questionSignal);
+                return custom?.trim() && custom.trim().toLowerCase() !== '/cancel' ? custom : declined();
+            }
+            const index = /^answer:(\d+)$/.exec(answer)?.[1];
+            if (index === undefined || !choices[Number(index)])
+                throw new Error('Invalid clarification selection');
+            return choices[Number(index)].replace(/\s*\(recommended\)/gi, '').trim();
+        },
+    };
+    let mcp;
+    let codeIntel;
+    let healthProviderFailed = false;
+    // The probes are billed requests this run made; they are collected per model and merged into
+    // the finish, including when the health check is what failed the run.
+    const probeModels = new Map();
+    const probeTelemetry = () => {
+        const capture = createRunTelemetry();
+        for (const probe of probeModels.values()) {
+            const provider = config.providers.find(item => item.id === probe.provider);
+            recordModelUse(capture, {
+                ...(provider === undefined ? {} : { providerType: provider.type, baseUrl: provider.baseUrl }),
+                model: probe.model, role: 'other', usage: probe.usage,
+            });
+        }
+        return capture;
+    };
+    try {
+        const selection = configuredGraphSelection(config, accountSubject);
+        let loadedGraph;
+        try {
+            loadedGraph = await loadAccessibleGraph(selection, signal);
+        }
+        catch (error) {
+            // The same fallback the CLI terminal applies to a saved selection: a browser session
+            // cannot arm a model override, so a graph that cannot bind to this machine's providers
+            // runs as Default here with the reason said, rather than refusing a prompt the browser
+            // already accepted.
+            const providerGone = error instanceof GraphProviderUnavailableError;
+            if (!(providerGone || error instanceof PaidMembershipRequiredError))
+                throw error;
+            await notice(providerGone
+                ? 'The selected graph cannot run on this machine as configured, so its tasks cannot start here. Using the local Software Engineer graph.'
+                : error instanceof FreeTierLimitError ? `${error.message} Using the local Software Engineer graph.`
+                    : 'The selected graph needs paid account access. Using the local Software Engineer graph.');
+            loadedGraph = await loadAccessibleGraph('default', signal);
+        }
+        const health = await checkGraphModelHealth(loadedGraph, config, signal, {
+            onUsage: (delta, reference) => {
+                const key = `${reference.provider}\0${reference.model}`;
+                const entry = probeModels.get(key) ?? { provider: reference.provider, model: reference.model, usage: {} };
+                for (const field of ['requests', 'inputTokens', 'outputTokens', 'cacheRead', 'cacheWrite']) {
+                    const value = delta[field];
+                    if (typeof value === 'number')
+                        entry.usage[field] = (entry.usage[field] ?? 0) + value;
+                }
+                probeModels.set(key, entry);
+            },
+        });
+        if (!health.healthy) {
+            // A probe the provider rejected is a provider failure, not an infrastructure one; the
+            // finalizer reports the class so failure metrics stay comparable with the CLI's.
+            healthProviderFailed = health.failures.some(failure => failure.providerError === true);
+            throw new Error(formatGraphHealthFailure(health));
+        }
+        const graph = validateGraph(loadedGraph, { providers: config.providers, defaultProvider: config.provider, spawnAvailable: true });
+        // The id comes from the graph that survived the fallback, not the saved selection: a run that
+        // fell back to Software Engineer must not be reported as the custom graph it replaced.
+        Object.assign(telemetryHandle.dimensions, { graphId: graph.id, ...graphShape(graph) });
+        await beginTelemetry();
+        // Browser-owned runs can only supply { task } and no run state. Fail fast
+        // with the CLI affordance instead of letting graph validation reject an
+        // already accepted prompt with an opaque schema error.
+        try {
+            if (graph.inputSchema)
+                validateValue(graph.inputSchema, { task }, 'Run inputs');
+            if (graph.stateSchema)
+                validateValue(graph.stateSchema, {}, 'Run state');
+        }
+        catch (error) {
+            throw new Error(`This graph needs run inputs or state that browser sessions cannot provide. Run it from the CLI terminal with --run-input/--run-state, or select a graph that accepts only the task. (${error instanceof Error ? error.message : String(error)})`);
+        }
+        const workspaceGuidance = await loadWorkspaceInstructions(workspace, signal, config.systemPromptOverride);
+        const snapshot = await extensionSnapshot(config, signal);
+        for (const message of snapshot.notices)
+            await notice(message);
+        mcp = Object.keys(snapshot.servers).length
+            ? await connectMcpServers(snapshot.servers, context, message => { void notice(message).catch(() => { }); }, signal)
+            : { tools: [], close: async () => { } };
+        const homeWorkspace = workspace === await realpath(homedir()).catch(() => homedir());
+        codeIntel = await CodeIntelligenceManager.create({ workspace, permissions, onEvent,
+            config: homeWorkspace ? { ...resolveCodeIntelConfig(config), enabled: false, enabledRepos: [] } : resolveCodeIntelConfig(config) });
+        const adapters = (provider) => trajectory.wrap(createAdapter(provider), () => ({ runId, providerId: provider.id }));
+        const resolvedModels = new Map();
+        const refreshed = await refreshModelContext(selected, signal);
+        // The seeded entry carries the provider identity too: a cache hit here is the normal path for
+        // the selected provider, and omitting it bucketed every root-model request as `other`.
+        resolvedModels.set(JSON.stringify([selected.id, selected.model]), Promise.resolve({ model: refreshed.model,
+            adapter: adapters(refreshed), contextWindow: refreshed.contextWindow, providerType: selected.type, baseUrl: selected.baseUrl }));
+        const membership = config.jevEnabled === false ? { paid: false } : await getMembership(signal, directory);
+        const commandMemory = config.commandMemory === false ? undefined : await LocalToolMemory.open({ workspace, directory });
+        signal.throwIfAborted();
+        const result = await runGraph(graph, {
+            task, runId, provider: selected.id, model: refreshed.model, adapter: adapters(refreshed), contextWindow: refreshed.contextWindow,
+            tools: [...createTools(), ...snapshot.tools, ...mcp.tools], history: (session.contextHistory ?? session.history).slice(-6),
+            instructions: `${workspaceGuidance}\n${QA_SYSTEM_GUIDANCE}${snapshot.instructions}`,
+            context, codeIntel, commandMemory, todoStore: new TodoStore(),
+            ...hostedDecisionPolicy(membership, config.jevEnabled !== false, config.decisions), limits: resolveConfiguredLimits(config),
+            getSteeringMessages: async () => control.steering().map(content => ({ role: 'user', content })),
+            onEvent,
+            resolveModel: (id, model, modelSignal) => {
+                const provider = config.providers.find(item => item.id === id);
+                if (!provider)
+                    throw new Error(`Unknown provider: ${id}. Configure it with /providers in the CLI.`);
+                const key = JSON.stringify([id, model || provider.model]);
+                let pending = resolvedModels.get(key);
+                if (!pending) {
+                    pending = resolveModelContext(provider, model || provider.model, AbortSignal.any([signal, modelSignal]))
+                        .then(resolved => ({ model: resolved.model, adapter: adapters(resolved), contextWindow: resolved.contextWindow, providerType: provider.type, baseUrl: provider.baseUrl }));
+                    resolvedModels.set(key, pending);
+                    void pending.catch(() => { if (resolvedModels.get(key) === pending)
+                        resolvedModels.delete(key); });
+                }
+                return pending;
+            },
+            resolveProvider: id => {
+                const provider = config.providers.find(item => item.id === id);
+                if (!provider)
+                    throw new Error(`Unknown provider: ${id}. Configure it with /providers in the CLI.`);
+                return { model: provider.model, adapter: adapters(provider), contextWindow: provider.contextWindow, providerType: provider.type, baseUrl: provider.baseUrl };
+            },
+        });
+        const finishedTelemetry = result.telemetry ?? createRunTelemetry();
+        for (const probe of probeModels.values()) {
+            const provider = config.providers.find(item => item.id === probe.provider);
+            recordModelUse(finishedTelemetry, {
+                ...(provider === undefined ? {} : { providerType: provider.type, baseUrl: provider.baseUrl }),
+                model: probe.model, role: 'other', usage: probe.usage,
+            });
+        }
+        await reportRunFinished(telemetrySurface, telemetryHandle, {
+            status: result.status, ...(result.reason === undefined ? {} : { reason: result.reason }),
+            ...(result.providerRequestFailed ? { providerRequestFailed: true } : {}),
+            ...(result.providerOverflow ? { providerOverflow: true } : {}),
+            ...(result.telemetry !== undefined || probeModels.size > 0 ? { telemetry: finishedTelemetry } : {}),
+            toolCalls: result.toolCalls,
+        });
+        return trajectory.sanitize(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await beginTelemetry().catch(() => { });
+        await reportRunFinished(telemetrySurface, telemetryHandle, { status: signal.aborted ? 'cancelled' : 'infrastructure_error', reason: message,
+            ...(healthProviderFailed ? { providerRequestFailed: true } : {}),
+            ...(probeModels.size > 0 ? { telemetry: probeTelemetry() } : {}) }).catch(() => { });
+        const sanitized = trajectory.sanitize(message);
+        if (sanitized !== message)
+            throw new Error(sanitized);
+        throw error;
+    }
+    finally {
+        // Per-run cleanup must never close another CLI/browser conversation's resources.
+        await Promise.allSettled([mcp?.close(), codeIntel?.dispose(), disposeBrowserSessions(browserSessionOwner)]);
+        await trajectory.flush();
+        await drainTelemetry(telemetrySurface).catch(() => { });
+    }
+}

package/dist/src/browser-server.d.ts

@@ -0,0 +1,31 @@
+import { type SavedSession } from './sessions.js';
+import type { RuntimeEvent } from './types.js';
+import type { RunResult } from './runtime.js';
+export interface BrowserTaskControl {
+    signal: AbortSignal;
+    steering: () => string[];
+    event: (event: RuntimeEvent) => Promise<void>;
+    ask: (kind: 'question' | 'approval', question: string, signal: AbortSignal, choices?: {
+        id: string;
+        label: string;
+    }[]) => Promise<string | undefined>;
+}
+export interface BrowserServerOptions {
+    directory?: string;
+    runTask?: (session: SavedSession, task: string, control: BrowserTaskControl) => Promise<RunResult>;
+}
+/**
+ * A required save found this session's mutation lock held by another writer, so its round did not happen.
+ *
+ * The message is what the surface shows; the type is what lets the one caller that owes a completed turn
+ * retry it, instead of treating contention and a broken filesystem as the same answer.
+ */
+export declare class SessionSaveContendedError extends Error {
+}
+export declare function startBrowserServer(options?: BrowserServerOptions): Promise<{
+    origin: string;
+    token: string;
+    url: string;
+    close(): Promise<void>;
+}>;
+export declare function openBrowserUrl(url: string): void;