@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/lib/types/host/services/notify/index.js

@@ -0,0 +1,263 @@
+/**
+ * Notification capability: records finished runs, serves them, and pushes them.
+ *
+ * Where it sits. `dsh-session` already owns the durable answer to "what
+ * happened" (the append-only log) and `dsh-agent` owns the live answer to "is
+ * anything still running" (`agent/status`). This domain adds the third thing
+ * neither provides: a small, recent, cross-surface answer to "did the work I
+ * left running finish, and how did it end" that a phone or a desktop fleet list
+ * can read without holding a session log.
+ *
+ * What it therefore does NOT do. It keeps no durable copy of anything the
+ * session log already holds — see `core/notify/feed.ts` for why the notice log
+ * is deliberately in-memory. It records nothing for subagent sessions, because
+ * a child's turns are internal to a parent's work and a dot that lights up for
+ * every delegation is a dot nobody trusts. It records nothing for a turn that
+ * never entered a step, because an empty turn is not finished work.
+ *
+ * Two delivery shapes, one setting. `each-turn` reports every finished turn;
+ * `idle` waits until the agent has no driver left and reports the batch, which
+ * is what a notification is for. The feed ignores the setting entirely and
+ * always records every eligible turn, so a client's badge stays accurate no
+ * matter which push shape the deployment chose.
+ *
+ * @module dsh-web-all/notify
+ */
+import { hostname } from 'node:os';
+import { NOTIFY_MAX_LIMIT } from "../../../core/notify/contract.js";
+import { NoticeLog, TitleBook, textOfContent } from "../../../core/notify/feed.js";
+import { registerResources } from "../resources.js";
+import { accessTrustOf } from "../access-trust/index.js";
+import { familyNamespace, onFamilyConfigChange } from "../family-config.js";
+import { LARK_INBOX_SETTINGS_NAMESPACE } from "../lark-inbox/config.js";
+import { NOTIFY_SETTINGS_NAMESPACE, effectiveConfig, normalizeRecipients, resolveFeishuCredentials, } from "./config.js";
+import { FeishuSender } from "./feishu-sender.js";
+import { makeNotifyRoutes } from "./host-routes.js";
+export { Config, NOTIFY_SETTINGS_NAMESPACE, resolveFeishuCredentials } from "./config.js";
+export { FeishuSender, composeFeishuText } from "./feishu-sender.js";
+export { makeNotifyRoutes, readFeedQuery, requestAuthority } from "./host-routes.js";
+/** Turns buffered for one session before the oldest are dropped. */
+const PENDING_TURN_CAP = 20;
+/**
+ * Whether a session belongs to a subagent.
+ *
+ * `delegationDepth` is the durable field (a resumed child keeps its depth);
+ * `origin` is the coarser presentation marker. Either one answering "child" is
+ * enough, because recording a child's finished turn would put internal
+ * delegation on the same list as the user's own work.
+ *
+ * @param session - the session the event belongs to.
+ * @returns true when the session is a subagent child.
+ */
+export function isSubagentSession(session) {
+    const header = session?.header;
+    if (header === undefined)
+        return false;
+    if (header.origin === 'subagent')
+        return true;
+    const depth = header.delegationDepth;
+    return typeof depth === 'number' && depth > 0;
+}
+/**
+ * Register the notification capability.
+ *
+ * @param ctx - host plugin context.
+ * @param base - namespace value used when the family settings document has none.
+ * @param deps - injectables for tests.
+ * @returns the disposer releasing the route, the subscriptions and the sender.
+ */
+export function register(ctx, base = {}, deps = {}) {
+    const log = ctx.logger('notify');
+    const env = deps.env ?? process.env;
+    const hostLabel = deps.hostLabel ?? hostname();
+    // Retention is the contract's maximum so a settings change never renumbers
+    // notices; `feedLimit` only decides the default size of one read.
+    const notices = new NoticeLog(NOTIFY_MAX_LIMIT);
+    const titles = new TitleBook();
+    /** Turns that entered a step, keyed `${sessionId}\u0000${turn}`. */
+    const enteredSteps = new Set();
+    /** Notices waiting for their session's agent to go idle, in `idle` mode only. */
+    const pending = new Map();
+    let active = effectiveConfig(base);
+    let sender;
+    const current = () => familyNamespace(NOTIFY_SETTINGS_NAMESPACE) ?? base;
+    const stepKey = (sessionId, turn) => `${sessionId}\u0000${turn}`;
+    const buffered = (sessionId) => active.feishuMode === 'idle';
+    /** Model-facing label for one session, refreshed from the title event. */
+    const nameOf = (sessionId) => titles.titleOf(sessionId);
+    const wantOutcome = (notice) => active.feishuOutcomes.includes(notice.outcome);
+    const deliver = (batch) => {
+        if (sender === undefined)
+            return;
+        const worthy = batch.filter(wantOutcome);
+        if (worthy.length === 0)
+            return;
+        // Fire and forget: a delivery failure must never reach the session log's
+        // append path, which is synchronous and must not wait on a network call.
+        void sender.notify(worthy).catch(error => {
+            log.warn('dsh-notify: 推送失败：%s', error instanceof Error ? error.message : String(error));
+        });
+    };
+    const buffer = (notice) => {
+        const list = pending.get(notice.sessionId);
+        if (list === undefined) {
+            pending.set(notice.sessionId, [notice]);
+            return;
+        }
+        list.push(notice);
+        if (list.length > PENDING_TURN_CAP)
+            list.splice(0, list.length - PENDING_TURN_CAP);
+    };
+    const flush = (sessionId) => {
+        const list = pending.get(sessionId);
+        if (list === undefined)
+            return;
+        pending.delete(sessionId);
+        deliver(list);
+    };
+    /** Rebuild the sender from the current settings; drop it when nothing can send. */
+    const syncSender = () => {
+        sender = undefined;
+        if (!active.enabled || !active.feishuEnabled)
+            return;
+        const recipients = normalizeRecipients(active.feishuRecipients);
+        if (recipients.length === 0) {
+            log.warn('dsh-notify: 已启用飞书推送但没有收件人（feishuRecipients），未创建发送器');
+            return;
+        }
+        let credentials;
+        try {
+            credentials = resolveFeishuCredentials(active, familyNamespace(LARK_INBOX_SETTINGS_NAMESPACE), env);
+        }
+        catch (error) {
+            log.warn('dsh-notify: %s', error instanceof Error ? error.message : String(error));
+            return;
+        }
+        if (credentials === null) {
+            log.warn('dsh-notify: 已启用飞书推送但缺少应用凭据（feishuAppId / feishuAppSecret，或 lark-inbox 的 appId / appSecret）');
+            return;
+        }
+        const built = deps.createSender !== undefined
+            ? deps.createSender({ credentials, recipients, hostLabel })
+            : new FeishuSender({
+                credentials,
+                recipients,
+                hostLabel,
+                log: message => log.warn('%s', message),
+            });
+        if (built === null)
+            return;
+        sender = built;
+        log.info('dsh-notify: 飞书推送已就绪（应用来源 %s，收件人 %d，模式 %s）', credentials.source, recipients.length, active.feishuMode);
+    };
+    /**
+     * Apply a settings change without remounting.
+     *
+     * An edit while the capability runs keeps what it has recorded — changing the
+     * recipient list or the push shape must not wipe the results a client is part
+     * way through reading. Turning the capability OFF does drop them, because a
+     * disabled capability must not keep a list of the conversations this machine
+     * has been running, and because a later enable would otherwise publish a burst
+     * of results the user never chose to collect.
+     */
+    const sync = () => {
+        const wasEnabled = active.enabled;
+        active = effectiveConfig(current());
+        if (wasEnabled && !active.enabled) {
+            notices.clear();
+            pending.clear();
+            enteredSteps.clear();
+        }
+        syncSender();
+    };
+    return registerResources(own => {
+        own(ctx.on('session/event', (session, event) => {
+            if (!active.enabled)
+                return;
+            const sessionId = typeof session?.id === 'string' ? session.id : '';
+            if (sessionId === '' || isSubagentSession(session))
+                return;
+            const type = event?.type;
+            const data = event?.data;
+            if (type === 'session/title') {
+                const title = data?.title;
+                if (typeof title === 'string')
+                    titles.setTitle(sessionId, title);
+                return;
+            }
+            const at = typeof event?.time === 'number' ? event.time : Date.now();
+            if (type === 'user/message') {
+                const source = data?.source;
+                // Only a human prompt may name a session: the same event type also
+                // carries synthetic injections (file-change notices, cron wakes, skill
+                // content), and quoting one of those as the conversation's name would
+                // be wrong in a way the user cannot correct.
+                if (source?.kind === 'user') {
+                    titles.rememberPrompt(sessionId, textOfContent(data?.content));
+                }
+                return;
+            }
+            if (type === 'step/start') {
+                const turn = data?.turn;
+                if (typeof turn === 'number')
+                    enteredSteps.add(stepKey(sessionId, turn));
+                return;
+            }
+            if (type !== 'turn/end')
+                return;
+            const payload = data;
+            const turn = typeof payload?.turn === 'number' ? payload.turn : -1;
+            // A turn that never entered a step did no work, so there is nothing to
+            // report; recording it would make every cancelled empty prompt a notice.
+            const key = stepKey(sessionId, turn);
+            if (!enteredSteps.delete(key))
+                return;
+            const reason = typeof payload?.reason?.kind === 'string' ? payload.reason.kind : '';
+            const notice = notices.append({ at, sessionId, title: nameOf(sessionId), turn, reason });
+            if (buffered(sessionId))
+                buffer(notice);
+            else
+                deliver([notice]);
+        }));
+        own(ctx.on('agent/status', (payload) => {
+            if (!active.enabled)
+                return;
+            if (payload?.status !== 'idle')
+                return;
+            const sessionId = typeof payload.agent?.id === 'string' ? payload.agent.id : '';
+            if (sessionId === '')
+                return;
+            flush(sessionId);
+        }));
+        own(ctx.on('session/disposed', (session) => {
+            const sessionId = typeof session?.id === 'string' ? session.id : '';
+            if (sessionId === '')
+                return;
+            titles.forget(sessionId);
+            pending.delete(sessionId);
+            // Dropping the entered-step marks keeps the set from growing with the
+            // process: a session that is disposed can no longer close a turn.
+            for (const key of [...enteredSteps]) {
+                if (key.startsWith(`${sessionId}\u0000`))
+                    enteredSteps.delete(key);
+            }
+        }));
+        for (const route of makeNotifyRoutes({
+            log: () => notices,
+            defaultLimit: () => active.feedLimit,
+            isTrusted: request => accessTrustOf(ctx).isTrusted(request),
+            enabled: () => active.enabled,
+        }))
+            own(ctx.webServer.register(route));
+        own(onFamilyConfigChange(() => {
+            try {
+                sync();
+            }
+            catch (error) {
+                log.warn('dsh-notify: 应用设置失败：%s', error instanceof Error ? error.message : String(error));
+            }
+        }));
+        sync();
+        log.info('dsh-notify: 能力已挂载（%s）', active.enabled ? '启用' : '停用');
+    });
+}

package/lib/types/host/services/playwright-sessions/child.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One per-session Playwright MCP child process.
+ *
+ * Each conversation owns a dedicated `@playwright/mcp` server spawned over
+ * stdio with a per-session `--user-data-dir` (browser profile) and `cwd`
+ * (screenshot / file output). Because every child serves exactly one MCP
+ * client, no `--shared-browser-context` or `--isolated` flag is needed: the
+ * default per-client browser model already gives this session a private
+ * browser, and the explicit user-data-dir keeps its login state durable
+ * without ever touching another session's profile.
+ *
+ * In `liveView` mode the host starts the persistent Chromium itself with
+ * `launchPersistentContext` (CDP endpoint on an ephemeral port) and passes
+ * `--cdp-endpoint` to the MCP child, which connects to that SAME browser as
+ * its default context. The host keeps the `BrowserContext` handle so the
+ * live-view WebSocket (see live-view.ts) can stream CDP screencast frames of
+ * the pages the MCP tools drive. This is the dual-owner launch path the
+ * older implementation documented; without `liveView` the child launches its
+ * own browser exactly as before.
+ */
+import { type BrowserContext } from 'playwright-core';
+import type { PlaywrightConnectionMode } from '../../../core/playwright-sessions/contracts.ts';
+export interface SessionBrowserOptions {
+    /** Absolute path to the @playwright/mcp cli.js entry. */
+    cliPath: string;
+    /** Durable session identity used for the profile directory name. */
+    sessionId: string;
+    /** Root directory holding every session's profile + output folders. */
+    sessionsRoot: string;
+    /** Environment for the child; PLAYWRIGHT_BROWSERS_PATH is expected here. */
+    env: Record<string, string>;
+    mode: PlaywrightConnectionMode;
+    headless: boolean;
+    browserChannel: 'chrome' | 'msedge';
+    executablePath: string;
+    allowedHosts: string[];
+    allowedOrigins: string[];
+    blockedOrigins: string[];
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /**
+     * Dual-owner mode: the host starts the persistent Chromium and the MCP
+     * child connects over `--cdp-endpoint`; the returned browser exposes the
+     * `context` handle for the live view. False (default) keeps the plain
+     * child-launched browser with no live view.
+     */
+    liveView?: boolean;
+}
+export interface SessionBrowser {
+    readonly sessionId: string;
+    /** Durable per-session profile directory (user-data-dir). */
+    readonly profileDir: string;
+    /** Per-session output directory (screenshots, saved files). */
+    readonly outputDir: string;
+    /** Forward one raw MCP tool call to this session's browser. */
+    call(rawName: string, args: unknown, signal?: AbortSignal): Promise<SessionBrowserResult>;
+    /** Close the browser (equivalent to the browser_close tool). */
+    close(): Promise<void>;
+    /** Close the browser and terminate the child process. */
+    dispose(): Promise<void>;
+    /** The host-owned persistent context (liveView mode only). */
+    readonly context?: BrowserContext | null;
+}
+export interface SessionBrowserResult {
+    content: unknown[];
+    isError: boolean;
+}
+/** Read the ephemeral CDP endpoint Chromium chose (DevToolsActivePort:
+ *  first line = port, second line = browser websocket path). */
+export declare function readCdpEndpoint(profileDir: string): string;
+/** Poll for the CDP port file with a bounded wait. */
+export declare function waitForCdpEndpoint(profileDir: string, timeoutMs?: number): Promise<string>;
+export declare function createSessionBrowser(options: SessionBrowserOptions): Promise<SessionBrowser>;
+/** Best-effort text rendering of an MCP content array for error paths. */
+export declare function extractText(content: unknown[] | undefined, rawName: string): string;
+//# sourceMappingURL=child.d.ts.map

package/lib/types/host/services/playwright-sessions/child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/playwright-sessions/child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gDAAgD,CAAA;AAE9F,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3B,IAAI,EAAE,wBAAwB,CAAA;IAC9B,QAAQ,EAAE,OAAO,CAAA;IACjB,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAAA;IACnC,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACzF,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,yDAAyD;IACzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,EAAE,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB;AAWD;gEACgE;AAChE,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,sDAAsD;AACtD,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,SAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAYlH;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CA6HlG;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWnF"}

package/lib/types/host/services/playwright-sessions/child.js

@@ -0,0 +1,197 @@
+/**
+ * One per-session Playwright MCP child process.
+ *
+ * Each conversation owns a dedicated `@playwright/mcp` server spawned over
+ * stdio with a per-session `--user-data-dir` (browser profile) and `cwd`
+ * (screenshot / file output). Because every child serves exactly one MCP
+ * client, no `--shared-browser-context` or `--isolated` flag is needed: the
+ * default per-client browser model already gives this session a private
+ * browser, and the explicit user-data-dir keeps its login state durable
+ * without ever touching another session's profile.
+ *
+ * In `liveView` mode the host starts the persistent Chromium itself with
+ * `launchPersistentContext` (CDP endpoint on an ephemeral port) and passes
+ * `--cdp-endpoint` to the MCP child, which connects to that SAME browser as
+ * its default context. The host keeps the `BrowserContext` handle so the
+ * live-view WebSocket (see live-view.ts) can stream CDP screencast frames of
+ * the pages the MCP tools drive. This is the dual-owner launch path the
+ * older implementation documented; without `liveView` the child launches its
+ * own browser exactly as before.
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { chromium as playwrightChromium } from 'playwright-core';
+import { sanitizePlaywrightSessionKey } from "../../../core/playwright-sessions/names.js";
+const STDERR_CAPTURE_LIMIT = 8192;
+/** Wait for the DevToolsActivePort file after launching Chromium. */
+const CDP_PORT_FILE_TIMEOUT_MS = 15_000;
+/** The file Chromium writes with its --remote-debugging-port=0 choice. */
+function cdpPortFile(profileDir) {
+    return join(profileDir, 'DevToolsActivePort');
+}
+/** Read the ephemeral CDP endpoint Chromium chose (DevToolsActivePort:
+ *  first line = port, second line = browser websocket path). */
+export function readCdpEndpoint(profileDir) {
+    const lines = readFileSync(cdpPortFile(profileDir), 'utf8').trim().split('\n');
+    const port = Number.parseInt(lines[0] ?? '', 10);
+    if (!Number.isFinite(port) || port <= 0)
+        throw new Error(`unreadable DevToolsActivePort: ${lines.join(' | ').slice(0, 80)}`);
+    const wsPath = (lines[1] ?? '').trim();
+    return `ws://127.0.0.1:${port}${wsPath === '' ? '' : wsPath}`;
+}
+/** Poll for the CDP port file with a bounded wait. */
+export async function waitForCdpEndpoint(profileDir, timeoutMs = CDP_PORT_FILE_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            return readCdpEndpoint(profileDir);
+        }
+        catch (error) {
+            lastError = error;
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+    }
+    throw new Error(`CDP port file did not appear within ${timeoutMs}ms` + (lastError !== undefined ? ` (${String(lastError)})` : ''));
+}
+export async function createSessionBrowser(options) {
+    const profileDir = join(options.sessionsRoot, sanitizePlaywrightSessionKey(options.sessionId));
+    const outputDir = join(profileDir, 'output');
+    mkdirSync(outputDir, { recursive: true });
+    // Dual-owner mode: the host owns the persistent Chromium, the MCP child
+    // connects to it over the CDP endpoint. The context handle is kept for the
+    // live-view screencast.
+    let hostedContext = null;
+    const args = [
+        options.cliPath,
+        '--allowed-hosts',
+        options.allowedHosts.join(','),
+        '--output-dir',
+        outputDir,
+    ];
+    if (options.allowedOrigins.length > 0)
+        args.push('--allowed-origins', options.allowedOrigins.join(';'));
+    if (options.blockedOrigins.length > 0)
+        args.push('--blocked-origins', options.blockedOrigins.join(';'));
+    if (options.mode === 'extension') {
+        // The official extension opens its own connection/approval page in the
+        // selected Chrome profile and exposes only the tabs assigned to this MCP
+        // client. The external browser remains owned by the user.
+        args.push('--extension', '--browser', options.browserChannel);
+        if (options.executablePath !== '')
+            args.push('--executable-path', options.executablePath);
+    }
+    else {
+        if (options.headless)
+            args.push('--headless');
+        if (options.liveView === true) {
+            hostedContext = await playwrightChromium.launchPersistentContext(profileDir, {
+                headless: options.headless,
+                args: ['--remote-debugging-port=0'],
+                env: options.env,
+            });
+            const endpoint = await waitForCdpEndpoint(profileDir);
+            args.push('--cdp-endpoint', endpoint);
+        }
+        else {
+            args.push('--user-data-dir', profileDir);
+        }
+    }
+    const childEnv = options.env;
+    let stderrCapture = '';
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args,
+        cwd: outputDir,
+        env: childEnv,
+        stderr: 'pipe',
+    });
+    transport.stderr?.on('data', (chunk) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        if (stderrCapture.length < STDERR_CAPTURE_LIMIT) {
+            stderrCapture = (stderrCapture + text).slice(-STDERR_CAPTURE_LIMIT);
+        }
+    });
+    const client = new Client({ name: 'dsh-playwright-sessions', version: '1.0.0' });
+    let closed = false;
+    let closePromise;
+    const markClosed = () => {
+        closed = true;
+    };
+    client.onclose = markClosed;
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        if (hostedContext !== null) {
+            try {
+                await hostedContext.close();
+            }
+            catch { /* ignore */ }
+            hostedContext = null;
+        }
+        void transport.close().catch(() => { });
+        throw new Error(`playwright-sessions: failed to start browser for session ${options.sessionId}: ${String(error)}` +
+            (stderrCapture ? ` (child stderr: ${stderrCapture.slice(-2000)})` : ''));
+    }
+    const ensureOpen = () => {
+        if (closed) {
+            throw new Error(`playwright-sessions: browser for session ${options.sessionId} is closed` +
+                (stderrCapture ? ` (last child stderr: ${stderrCapture.slice(-1000)})` : ''));
+        }
+    };
+    const shutdown = async () => {
+        if (closePromise)
+            return closePromise;
+        closePromise = (async () => {
+            try {
+                await client.close();
+            }
+            catch {
+                // Transport may already be gone; nothing left to do.
+            }
+            if (hostedContext !== null) {
+                try {
+                    await hostedContext.close();
+                }
+                catch { /* ignore */ }
+                hostedContext = null;
+            }
+            closed = true;
+        })();
+        return closePromise;
+    };
+    return {
+        sessionId: options.sessionId,
+        profileDir,
+        outputDir,
+        context: hostedContext,
+        async call(rawName, args, signal) {
+            ensureOpen();
+            const result = await client.callTool({ name: rawName, arguments: (args ?? {}) }, undefined, { signal, timeout: options.toolCallTimeoutMs });
+            if (result.isError === true) {
+                throw new Error(extractText(result.content, rawName));
+            }
+            return { content: (result.content ?? []), isError: false };
+        },
+        close: shutdown,
+        dispose: shutdown,
+    };
+}
+/** Best-effort text rendering of an MCP content array for error paths. */
+export function extractText(content, rawName) {
+    const blocks = Array.isArray(content) ? content : [];
+    const texts = [];
+    for (const block of blocks) {
+        if (typeof block === 'object' && block !== null && block.type === 'text') {
+            const text = block.text;
+            if (typeof text === 'string')
+                texts.push(text);
+        }
+    }
+    if (texts.length > 0)
+        return texts.join('\n');
+    return blocks.length > 0 ? JSON.stringify(blocks) : `${rawName} returned no text content`;
+}

package/lib/types/host/services/playwright-sessions/controller.d.ts

@@ -0,0 +1,25 @@
+/** Attended, single-owner lease for the user's attached Chrome browser. */
+import type { ResolvedPlaywrightSessionsConfig } from '../../../core/playwright-sessions/contracts.ts';
+import { type PlaywrightConnectionStatus } from '../../../core/playwright-sessions/control.ts';
+import type { SessionBrowserManager } from './manager.ts';
+interface ControllerOptions {
+    config: ResolvedPlaywrightSessionsConfig;
+    manager: SessionBrowserManager;
+    sessionExists(sessionId: string): boolean | Promise<boolean>;
+}
+export declare class PlaywrightSessionsController {
+    private readonly options;
+    private ownerId;
+    private state;
+    private error;
+    private connectPromise;
+    constructor(options: ControllerOptions);
+    status(sessionId: string): PlaywrightConnectionStatus;
+    connect(sessionId: string): Promise<PlaywrightConnectionStatus>;
+    disconnect(sessionId: string): Promise<PlaywrightConnectionStatus>;
+    requireOwner(sessionId: string): void;
+    release(sessionId: string): void;
+    dispose(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=controller.d.ts.map

package/lib/types/host/services/playwright-sessions/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/playwright-sessions/controller.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAA;AACtG,OAAO,EAA0B,KAAK,0BAA0B,EAAE,MAAM,8CAA8C,CAAA;AACtH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAEzD,UAAU,iBAAiB;IACzB,MAAM,EAAE,gCAAgC,CAAA;IACxC,OAAO,EAAE,qBAAqB,CAAA;IAC9B,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7D;AAED,qBAAa,4BAA4B;IAM3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,KAAK,CAAwE;IACrF,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,cAAc,CAAiD;gBAE1C,OAAO,EAAE,iBAAiB;IAEvD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,0BAA0B;IAqB/C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAiC/D,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAQxE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAOrC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}

package/lib/types/host/services/playwright-sessions/controller.js

@@ -0,0 +1,104 @@
+import { PlaywrightControlError } from "../../../core/playwright-sessions/control.js";
+export class PlaywrightSessionsController {
+    options;
+    ownerId;
+    state = 'disconnected';
+    error;
+    connectPromise;
+    constructor(options) {
+        this.options = options;
+    }
+    status(sessionId) {
+        if (this.options.config.mode !== 'extension') {
+            return {
+                mode: this.options.config.mode,
+                state: 'unavailable',
+                ownedByThisSession: false,
+                busy: false,
+                liveView: this.options.config.liveView,
+            };
+        }
+        const ownedByThisSession = this.ownerId === sessionId;
+        return {
+            mode: 'extension',
+            state: ownedByThisSession ? this.state : 'disconnected',
+            ownedByThisSession,
+            busy: this.ownerId !== undefined && !ownedByThisSession,
+            liveView: false,
+            ...(ownedByThisSession && this.error !== undefined ? { errorCode: this.error.code, errorMessage: this.error.message } : {}),
+        };
+    }
+    async connect(sessionId) {
+        if (this.options.config.mode !== 'extension')
+            throw new PlaywrightControlError('wrong-mode', 'Chrome extension mode is not enabled');
+        if (!await this.options.sessionExists(sessionId))
+            throw new PlaywrightControlError('not-found', 'session does not exist');
+        if (this.ownerId !== undefined && this.ownerId !== sessionId)
+            throw new PlaywrightControlError('busy', 'Chrome is already connected to another session');
+        if (this.ownerId === sessionId && this.state === 'connected')
+            return this.status(sessionId);
+        if (this.ownerId === sessionId && this.connectPromise !== undefined)
+            return this.connectPromise;
+        this.ownerId = sessionId;
+        this.state = 'connecting';
+        this.error = undefined;
+        const run = (async () => {
+            try {
+                const browser = await this.options.manager.get(sessionId);
+                // Browser creation is lazy inside Playwright MCP. This harmless call
+                // deliberately opens the official extension approval/tab picker.
+                await browser.call('browser_tabs', { action: 'list' });
+                this.state = 'connected';
+                return this.status(sessionId);
+            }
+            catch (cause) {
+                await this.options.manager.dispose(sessionId);
+                if (this.ownerId === sessionId) {
+                    this.ownerId = undefined;
+                    this.state = 'disconnected';
+                    this.error = undefined;
+                }
+                const message = cause instanceof Error ? cause.message : String(cause);
+                throw new PlaywrightControlError('connect-failed', message);
+            }
+        })();
+        this.connectPromise = run;
+        try {
+            return await run;
+        }
+        finally {
+            if (this.connectPromise === run)
+                this.connectPromise = undefined;
+        }
+    }
+    async disconnect(sessionId) {
+        if (this.options.config.mode !== 'extension')
+            throw new PlaywrightControlError('wrong-mode', 'Chrome extension mode is not enabled');
+        if (this.ownerId !== undefined && this.ownerId !== sessionId)
+            throw new PlaywrightControlError('not-owner', 'this session does not own the Chrome connection');
+        await this.options.manager.dispose(sessionId);
+        this.release(sessionId);
+        return this.status(sessionId);
+    }
+    requireOwner(sessionId) {
+        if (this.options.config.mode !== 'extension')
+            return;
+        if (sessionId === '' || this.ownerId !== sessionId || this.state !== 'connected') {
+            throw new PlaywrightControlError('not-owner', 'Connect this session from the Agent Browser panel before using local Chrome');
+        }
+    }
+    release(sessionId) {
+        if (this.ownerId !== sessionId)
+            return;
+        this.ownerId = undefined;
+        this.state = 'disconnected';
+        this.error = undefined;
+        this.connectPromise = undefined;
+    }
+    async dispose() {
+        const owner = this.ownerId;
+        if (owner !== undefined)
+            await this.options.manager.dispose(owner);
+        this.release(owner ?? '');
+    }
+}