@webhands/core 0.1.0 → 0.3.0

package/src/playwright-launch-transport.ts

@@ -1,25 +1,98 @@
 import {stat} from 'node:fs/promises';
+import {chromium, type BrowserContext, type Page} from 'playwright';
 import {
-	chromium,
-	errors as pwErrors,
-	type BrowserContext,
-	type Page as PwPage,
-} from 'playwright';
-import {MissingBrowserBinaryError, MissingProfileError} from './errors.js';
+	MissingBrowserBinaryError,
+	MissingProfileError,
+	MissingStealthDependencyError,
+} from './errors.js';
+import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
 import {
 	resolveProfileLocation,
 	type ProfileLocationOptions,
 } from './profile-location.js';
-import type {
-	Cookie,
-	OpenTarget,
-	Page,
-	Session,
-	Snapshot,
-	SnapshotOptions,
-	Transport,
-	WaitCondition,
-} from './seam.js';
+import type {OpenTarget, Session, Transport} from './seam.js';
+
+/**
+ * The subset of Playwright's `chromium` browser type the launch transport uses.
+ *
+ * Patchright is an API-compatible Playwright fork, so its `chromium` has the
+ * SAME shape (ADR-0003 stays intact: this structural type, like Playwright's
+ * own types, is confined to this module and never crosses the seam). We type the
+ * lazily-imported stealth chromium against THIS rather than importing any
+ * Patchright type, so the dependency stays optional at the type level too.
+ */
+type ChromiumLauncher = Pick<typeof chromium, 'launchPersistentContext'>;
+
+/** The shape `await import('patchright')` is expected to expose. */
+interface StealthModule {
+	readonly chromium: ChromiumLauncher;
+}
+
+/**
+ * How the transport obtains the stealth (`patchright`) chromium. This is an
+ * INTERNAL test seam, not a public API: tests inject a fake module (or a
+ * rejecting importer) here so no real browser/Patchright is needed, exactly as
+ * production uses the default lazy `import('patchright')`. It is deliberately
+ * NOT on {@link OpenTarget} (ADR-0003: the seam stays free of Playwright/CDP/
+ * Patchright concerns).
+ */
+export type StealthChromiumImporter = () => Promise<StealthModule>;
+
+/**
+ * Construction-time policy for {@link PlaywrightLaunchTransport}.
+ *
+ * Stealth is a TRANSPORT-CONSTRUCTION policy (which browser engine + launch
+ * flags to use), not a per-open target detail, so it lives here and NOT on
+ * {@link OpenTarget} (which stays Playwright/CDP-free per ADR-0003).
+ */
+export interface PlaywrightLaunchTransportOptions {
+	/**
+	 * Opt-in Patchright-backed stealth launch. Default `false` (vanilla
+	 * Playwright). When `true`, the transport launches via the lazily-imported
+	 * optional `patchright` package, which patches the CDP `Runtime.enable`
+	 * automation tell that anti-bot WAFs detect (ADR-0002 keeps this as one extra
+	 * layer, not a replacement for a real profile/IP). If `patchright` is not
+	 * installed it throws {@link MissingStealthDependencyError}; it NEVER silently
+	 * falls back to vanilla.
+	 */
+	readonly stealth?: boolean;
+	/**
+	 * Drive a browser ALREADY INSTALLED ON THE SYSTEM instead of the bundled
+	 * Chromium, named by its install identity (e.g. `'chrome'` to drive the system
+	 * Google Chrome, Patchright's recommended setup; also `'msedge'`,
+	 * `'chrome-beta'`, ...). Applies to BOTH stealth and vanilla launches when set.
+	 * When omitted, Playwright/Patchright's bundled Chromium is used.
+	 *
+	 * Maps to Playwright's `channel` launch option internally; we name it
+	 * `systemBrowser` so the public surface speaks domain language ("use a browser
+	 * I already have installed") rather than the Playwright term (ADR-0003 keeps
+	 * Playwright vocabulary out of the public surface).
+	 */
+	readonly systemBrowser?: string;
+	/**
+	 * INTERNAL test seam: override how the stealth chromium is imported. Omit in
+	 * production (defaults to `import('patchright')`). See
+	 * {@link StealthChromiumImporter}.
+	 */
+	readonly importStealthChromium?: StealthChromiumImporter;
+}
+
+/**
+ * The package name of the optional stealth dependency. Kept as a runtime value
+ * (not an `import('patchright')` literal) so TypeScript does NOT try to resolve
+ * its types at build time, since it is an OPTIONAL dependency that is legitimately
+ * absent when stealth is never enabled.
+ */
+const STEALTH_PACKAGE = 'patchright';
+
+/** The default lazy import of the OPTIONAL `patchright` dependency. */
+const defaultStealthImporter: StealthChromiumImporter = async () => {
+	// Indirect (non-literal specifier) so tsc/bundlers do not resolve the
+	// optional dep eagerly, and the module load never fails when it is absent;
+	// the import only runs when stealth is opted in.
+	const specifier = STEALTH_PACKAGE;
+	return (await import(specifier)) as unknown as StealthModule;
+};
 
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
@@ -37,17 +110,45 @@ import type {
  * `WEBHANDS_HOME` env var, or `~/.webhands`). See
  * {@link resolveProfileLocation}. Because that is a SHARED location, tests pass
  * a temp `root` (or set the env var) and assert the real home is untouched.
+ *
+ * STEALTH (opt-in, default OFF): the third constructor arg can enable a
+ * Patchright-backed launch ({@link PlaywrightLaunchTransportOptions}). Patchright
+ * is an OPTIONAL dependency imported lazily only when stealth is enabled; if it
+ * is absent the transport throws {@link MissingStealthDependencyError} rather
+ * than falling back to vanilla. This addresses ONLY the CDP `Runtime.enable`
+ * automation tell; a real profile/IP/session reputation still matter (ADR-0002).
  */
 export class PlaywrightLaunchTransport implements Transport {
 	readonly #location: ProfileLocationOptions;
+	readonly #hands: readonly Hand[];
+	readonly #stealth: boolean;
+	readonly #systemBrowser: string | undefined;
+	readonly #importStealthChromium: StealthChromiumImporter;
 
 	/**
 	 * @param location overrides for where profiles live (a `root` dir and/or an
 	 *   `env`). Omit in production to use `~/.webhands`; pass a temp
 	 *   `root` in tests to isolate the shared profile location.
+	 * @param hands explicitly-loaded third-party hands to compose alongside the
+	 *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
+	 *   the operator's explicit config; the transport does NOT discover them. Omit
+	 *   for the built-ins-only surface.
+	 * @param options transport-construction policy, notably the opt-in `stealth`
+	 *   toggle and optional `systemBrowser` (see
+	 *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
+	 *   bundled Chromium, stealth OFF.
 	 */
-	constructor(location: ProfileLocationOptions = {}) {
+	constructor(
+		location: ProfileLocationOptions = {},
+		hands: readonly Hand[] = [],
+		options: PlaywrightLaunchTransportOptions = {},
+	) {
 		this.#location = location;
+		this.#hands = hands;
+		this.#stealth = options.stealth === true;
+		this.#systemBrowser = options.systemBrowser;
+		this.#importStealthChromium =
+			options.importStealthChromium ?? defaultStealthImporter;
 	}
 
 	async open(target: OpenTarget): Promise<Session> {
@@ -72,14 +173,41 @@ export class PlaywrightLaunchTransport implements Transport {
 
 		const headless = target.headed !== true;
 
+		// Pick the engine: the lazily-imported stealth (Patchright) chromium when
+		// opted in, else vanilla Playwright's. Resolving the stealth module is where
+		// an absent optional dependency surfaces as the typed
+		// MissingStealthDependencyError (we never fall back to vanilla silently).
+		const launcher = this.#stealth
+			? await this.#resolveStealthLauncher()
+			: chromium;
+
+		// Launch options: forward headless, the optional systemBrowser (Playwright's
+		// `channel`, e.g. 'chrome' to drive system Chrome, Patchright's recommended
+		// setup), and for stealth drop Playwright's automation-flavoured default
+		// args so they cannot re-add the fingerprint Patchright just removed.
+		const launchOptions: Parameters<
+			typeof chromium.launchPersistentContext
+		>[1] = {headless};
+		if (this.#systemBrowser !== undefined) {
+			launchOptions.channel = this.#systemBrowser;
+		}
+		if (this.#stealth) {
+			launchOptions.ignoreDefaultArgs = ['--enable-automation'];
+		}
+
 		let context: BrowserContext;
 		try {
-			context = await chromium.launchPersistentContext(loc.profileDir, {
-				headless,
-			});
+			context = await launcher.launchPersistentContext(
+				loc.profileDir,
+				launchOptions,
+			);
 		} catch (cause) {
 			if (isMissingBrowserBinary(cause)) {
-				throw new MissingBrowserBinaryError('chromium', undefined, {cause});
+				// With systemBrowser set (e.g. 'chrome') the "binary missing" failure
+				// means the SYSTEM browser is absent, not the bundled Chromium; name
+				// what is actually missing so the CLI's fix message is accurate.
+				const browser = this.#systemBrowser ?? 'chromium';
+				throw new MissingBrowserBinaryError(browser, undefined, {cause});
 			}
 			throw cause;
 		}
@@ -88,7 +216,34 @@ export class PlaywrightLaunchTransport implements Transport {
 		// the single active page (PRD: single active session in v1). Create one if
 		// the build ever changes that invariant.
 		const pwPage = context.pages()[0] ?? (await context.newPage());
-		return makeSession(context, pwPage);
+		return makeSession(context, pwPage, this.#hands);
+	}
+
+	/**
+	 * Resolve the stealth (`patchright`) chromium via the injected lazy importer.
+	 *
+	 * Confines the brittle "optional dependency absent" detection to ONE spot
+	 * (mirroring {@link isMissingBrowserBinary}): any failure to import the
+	 * optional package becomes the typed {@link MissingStealthDependencyError}, so
+	 * the caller never silently degrades to vanilla Playwright.
+	 */
+	async #resolveStealthLauncher(): Promise<ChromiumLauncher> {
+		let mod: StealthModule;
+		try {
+			mod = await this.#importStealthChromium();
+		} catch (cause) {
+			throw new MissingStealthDependencyError('patchright', undefined, {
+				cause,
+			});
+		}
+		if (
+			mod === null ||
+			typeof mod !== 'object' ||
+			typeof mod.chromium?.launchPersistentContext !== 'function'
+		) {
+			throw new MissingStealthDependencyError('patchright');
+		}
+		return mod.chromium;
 	}
 }
 
@@ -107,6 +262,11 @@ async function isExistingDirectory(path: string): Promise<boolean> {
  * does not export a typed error for this, so we detect on the message (it
  * instructs the user to run `playwright install`). We confine that brittle
  * string match to this one spot and re-raise as a stable typed error.
+ *
+ * This also covers the `channel: 'chrome'` case, where the missing binary is the
+ * SYSTEM Chrome, not the bundled Chromium. Playwright phrases that as the
+ * channel/distribution not being found; we match those variants too so the
+ * stealth+system-Chrome path still yields the typed MissingBrowserBinaryError.
  */
 function isMissingBrowserBinary(cause: unknown): boolean {
 	const message = cause instanceof Error ? cause.message : String(cause ?? '');
@@ -115,12 +275,29 @@ function isMissingBrowserBinary(cause: unknown): boolean {
 		/please run the following command to download new browsers/i.test(
 			message,
 		) ||
-		/playwright install/i.test(message)
+		/playwright install/i.test(message) ||
+		// channel: 'chrome' (or other system channels) not installed on the host.
+		/Chromium distribution '.*' is not found/i.test(message) ||
+		/No "?(chrome|msedge|chromium)"? .* found/i.test(message)
 	);
 }
 
-/** Wrap a live Playwright persistent context into the seam's {@link Session}. */
-function makeSession(context: BrowserContext, pwPage: PwPage): Session {
+/**
+ * Wrap a live Playwright persistent context into the seam's {@link Session}.
+ *
+ * The VERB surface comes from the shared hand-host ({@link composeBuiltInPage}),
+ * which is the single place the eight built-in verbs are composed (no duplicated
+ * page-object literal). Only the SESSION LIFECYCLE is per-transport here: the
+ * launch transport listens on the context's `'close'` event and its `close()`
+ * calls `context.close()`, which KILLS the browser this transport spawned
+ * (contrast the attach transport, which detaches without killing the user's
+ * browser, ADR-0002).
+ */
+function makeSession(
+	context: BrowserContext,
+	pwPage: Page,
+	extraHands: readonly Hand[],
+): Session {
 	let closed = false;
 	const ensureOpen = () => {
 		if (closed) {
@@ -128,236 +305,45 @@ function makeSession(context: BrowserContext, pwPage: PwPage): Session {
 		}
 	};
 
-	const page: Page = {
-		async navigate(url: string): Promise<void> {
-			ensureOpen();
-			// "Settled" for `goto` = the `load` event: the document and its
-			// subresources have loaded (PRD story 6, "navigate ... and wait for it
-			// to settle"). We deliberately do NOT wait for `networkidle`:
-			// Playwright discourages it, and it hangs forever on pages with
-			// long-poll / streaming / analytics beacons (exactly the logged-in apps
-			// this tool targets). Content rendered AFTER load (XHR-injected prices,
-			// hydrated lists) is the job of the explicit `wait` verb (story 10), not
-			// of `goto`.
-			await pwPage.goto(url, {waitUntil: 'load'});
-		},
-		async snapshot(options?: SnapshotOptions): Promise<Snapshot> {
-			ensureOpen();
-			const url = pwPage.url();
-			if (options?.full === true) {
-				// `--full`: the raw DOM. `documentElement.outerHTML` is the serialized
-				// live DOM (post-script render), which is what an agent that wants the
-				// real HTML expects — not the original network response.
-				const content = await pwPage.evaluate(
-					() => document.documentElement.outerHTML,
-				);
-				return {url, view: 'full', content};
-			}
-			// Default: the token-cheap accessibility tree + visible text with stable
-			// `[ref=...]` element refs. Playwright's `ariaSnapshot({mode: 'ai'})`
-			// emits exactly that — a YAML aria tree (roles + accessible names +
-			// text) where each node carries a stable `[ref=eN]` reference, assigned
-			// deterministically by traversal order so re-snapshotting an unchanged
-			// page yields the same refs. The string crosses the seam as opaque,
-			// transport-neutral text (no Playwright type leaks, ADR-0003).
-			const content = await pwPage.ariaSnapshot({mode: 'ai'});
-			return {url, view: 'accessibility', content};
-		},
-		async click(t): Promise<void> {
-			ensureOpen();
-			await clickLocator(pwPage, t);
-		},
-		async type(t, text): Promise<void> {
-			ensureOpen();
-			await resolveLocator(pwPage, t).fill(text);
-		},
-		async eval(expression: string): Promise<unknown> {
-			ensureOpen();
-			// The `eval` escape hatch (PRD story 9): run the raw JS EXPRESSION in the
-			// page and return its serializable result. Playwright's `evaluate`
-			// already IS the seam's serialization contract (see {@link Page.eval}):
-			// it passes a string as an expression, awaits a returned Promise, and
-			// structurally clones the result out of the page by VALUE. That clone is
-			// richer than JSON: it preserves NaN/Infinity/BigInt and circular
-			// structures (back-refs become a `[Circular]` marker), yields `undefined`
-			// for functions/symbols, and returns an opaque preview string for a live
-			// host object (a DOM node never crosses the process boundary). A page-side
-			// throw rejects. We pass it straight through rather than re-encode it:
-			// wrapping the value in a transport-specific envelope would invent a
-			// dialect the seam deliberately avoids. The thrown error is a plain
-			// `Error`, so no Playwright/CDP type leaks across the seam (ADR-0003).
-			return pwPage.evaluate(expression);
-		},
-		async wait(condition: WaitCondition): Promise<void> {
-			ensureOpen();
-			await waitFor(pwPage, condition);
-		},
-		async cookies(): Promise<readonly Cookie[]> {
-			ensureOpen();
-			const raw = await context.cookies();
-			return raw.map(toSeamCookie);
-		},
-		async setCookies(cookies): Promise<void> {
-			ensureOpen();
-			await context.addCookies(cookies.map(fromSeamCookie));
-		},
+	// Resolves the first time the context is gone — whether the USER closed the
+	// window (Playwright fires the context 'close' event) or our own close()
+	// ran. This is what lets `setup-profile` hold the headed window open and
+	// block on waitForClose() until the human is done.
+	let resolveClosed!: () => void;
+	const closedSignal = new Promise<void>((resolve) => {
+		resolveClosed = resolve;
+	});
+	const markClosed = () => {
+		if (closed) return;
+		closed = true;
+		resolveClosed();
 	};
+	context.on('close', markClosed);
+
+	// Build the verb surface from the built-in hands over a live hand-context.
+	// The host keeps the live `pwPage`/`context` in-process (they never cross the
+	// seam, ADR-0003); the hand-context carries live page access only.
+	const handContext: HandContext = {pwPage, context, ensureOpen};
+	const {page, dispose: disposeHands} = composeWithHands(
+		handContext,
+		extraHands,
+	);
 
 	return {
 		page,
 		async close(): Promise<void> {
-			if (closed) return;
-			closed = true;
+			if (closed) {
+				return;
+			}
+			// Dispose the hands first (their in-process resources), THEN tear down
+			// the browser: context.close() fires the 'close' event, which runs
+			// markClosed and KILLS the browser this transport spawned.
+			await disposeHands();
 			await context.close();
+			markClosed();
+		},
+		waitForClose(): Promise<void> {
+			return closedSignal;
 		},
-	};
-}
-
-/**
- * Run the `wait` verb's three forms (PRD story 10) against a Playwright page.
- *
- * - `timeout` — pace by a fixed delay (`waitForTimeout`), so an agent can act
- *   like a human and let XHR-rendered content land.
- * - `locator` — block until the addressed element appears (`Locator.waitFor()`),
- *   the form for content rendered AFTER `goto` settled on `load`.
- * - `navigation` — block until the NEXT navigation settles to `load`. We use
- *   `waitForNavigation()` even though Playwright marks it `@deprecated` ("racy,
- *   use waitForURL"): that deprecation targets in-process TEST code that can arm
- *   the wait BEFORE the action and pass a target URL. Neither holds here. Across
- *   this seam verbs are DISCRETE sequential calls (`click` then `wait`), so we
- *   CANNOT arm before the trigger; and the realistic trigger is an async,
- *   JS-driven transition (a redirect / SPA route change that fires AFTER the
- *   agent's action, the "let XHR-rendered content load" case of story 10), so
- *   "wait for the NEXT navigation" is exactly right — whereas `waitForLoadState`
- *   would see the already-loaded current page and return before the pending
- *   transition. `waitForURL` is unusable because the verb has no target URL by
- *   design (the agent waits for "a navigation", not a known address). (See the
- *   task's ## Decisions note.)
- *
- * Shared by both Playwright transports so the verb behaviour stays identical
- * (the forward-note's "do NOT write a parallel second implementation").
- */
-export async function waitFor(
-	page: PwPage,
-	condition: WaitCondition,
-): Promise<void> {
-	switch (condition.kind) {
-		case 'timeout':
-			await page.waitForTimeout(condition.ms);
-			return;
-		case 'locator':
-			await resolveLocator(page, condition.target).waitFor();
-			return;
-		case 'navigation':
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			await page.waitForNavigation();
-			return;
-	}
-}
-
-/**
- * Resolve a raw Playwright locator EXPRESSION (ADR-0004) against the page. The
- * verb surface passes locator expressions like `getByRole('button', …)`; we
- * evaluate them in a small sandbox where `page`/`p` is the page, so the full
- * Playwright locator grammar is available without leaking the type across the
- * seam.
- *
- * Exported (with {@link clickLocator}/{@link waitFor}) so the attach transport
- * resolves locators IDENTICALLY — one resolution path, no parallel addressing
- * scheme (the forward-note's "do NOT write a parallel second implementation").
- */
-export function resolveLocator(page: PwPage, expression: string) {
-	// eslint-disable-next-line no-new-func
-	const factory = new Function('page', 'p', `return (${expression});`) as (
-		page: PwPage,
-		p: PwPage,
-	) => ReturnType<PwPage['locator']>;
-	return factory(page, page);
-}
-
-/**
- * How long a normal, actionability-checked `click` may wait before we treat the
- * element as un-clickable and fall back to a dispatched click. Short on purpose:
- * a hidden custom input never becomes actionable, so the regular click would
- * otherwise burn Playwright's full default timeout (30s) before the escape path
- * runs. The visible-element happy path clicks immediately and never hits this;
- * this bound is the latency cost paid ONLY on the hidden/non-actionable path,
- * and is long enough to tolerate a slow-but-eventually-actionable element
- * (animations, late layout) before deciding to dispatch.
- */
-const NORMAL_CLICK_TIMEOUT_MS = 1_000;
-
-/**
- * Run the `click` verb against a Playwright page (PRD story 8), shared by both
- * Playwright transports so the verb behaves identically (mirrors {@link waitFor};
- * the forward-note's "do NOT write a parallel second implementation").
- *
- * First try a normal `Locator.click()`, which AUTO-WAITS for the element to be
- * visible and actionable — the right behaviour for a real button. A hidden
- * custom input (the case the prd calls out) NEVER becomes actionable, so that
- * click times out; on a Playwright `TimeoutError` we fall back to
- * `dispatchEvent('click')`, which fires a click WITHOUT the actionability
- * checks. The fallback is deliberately the documented Playwright escape (a
- * sibling to the `eval` hatch, ADR-0004), not a reimplemented click: we keep
- * the locator a raw resolved expression and only change HOW the resolved
- * locator is clicked.
- *
- * Only a timeout triggers the fallback. The fallback `dispatchEvent` is itself
- * bounded by the same short timeout, so a locator that resolves NO element (a
- * bad locator) surfaces its timeout quickly instead of hanging the dispatch on
- * Playwright's 30s default — the dispatch escape is for elements that EXIST but
- * are not actionable (hidden custom inputs), not for absent ones.
- */
-export async function clickLocator(
-	page: PwPage,
-	expression: string,
-): Promise<void> {
-	const target = resolveLocator(page, expression);
-	try {
-		await target.click({timeout: NORMAL_CLICK_TIMEOUT_MS});
-	} catch (cause) {
-		if (!(cause instanceof pwErrors.TimeoutError)) {
-			throw cause;
-		}
-		// The element never became actionable (e.g. a hidden custom input). Fire
-		// the click without actionability checks, the prd's explicit escape path.
-		await target.dispatchEvent('click', {timeout: NORMAL_CLICK_TIMEOUT_MS});
-	}
-}
-
-/** Map a Playwright cookie to the transport-neutral seam {@link Cookie}. */
-function toSeamCookie(c: {
-	name: string;
-	value: string;
-	domain?: string;
-	path?: string;
-	expires?: number;
-	httpOnly?: boolean;
-	secure?: boolean;
-	sameSite?: 'Strict' | 'Lax' | 'None';
-}): Cookie {
-	return {
-		name: c.name,
-		value: c.value,
-		domain: c.domain,
-		path: c.path,
-		expires: c.expires,
-		httpOnly: c.httpOnly,
-		secure: c.secure,
-		sameSite: c.sameSite,
-	};
-}
-
-/** Map a seam {@link Cookie} to a Playwright cookie shape. */
-function fromSeamCookie(c: Cookie) {
-	return {
-		name: c.name,
-		value: c.value,
-		domain: c.domain,
-		path: c.path,
-		expires: c.expires,
-		httpOnly: c.httpOnly,
-		secure: c.secure,
-		sameSite: c.sameSite,
 	};
 }

package/src/remote-session.ts

@@ -1,4 +1,5 @@
 import {
+	callHandVerb,
 	makeRpcPage,
 	SESSION_RPC_PATH,
 	type SessionRpcRequest,
@@ -11,7 +12,7 @@ import type {Session} from './seam.js';
  * long-lived `serve` process over HTTP (ADR-0005).
  *
  * Each `webhands <verb>` is a thin client: it cannot hold a JS
- * reference to the server's live page, so this proxy turns every {@link Page}
+ * reference to the server's live page, so this proxy turns every {@link WebHandsPage}
  * verb into a session-RPC call to the running server (see `session-rpc.ts`) and
  * returns the result. The verb command code is UNCHANGED — it still calls
  * `provider(target)` then runs verbs against the returned `Session.page` then
@@ -24,8 +25,21 @@ import type {Session} from './seam.js';
  * (`stop`), exactly as ADR-0005 requires. This is the whole reason cross-
  * invocation persistence works: the page state survives because the client's
  * `close()` does not reach across to the server's session.
+ *
+ * THIRD-PARTY HAND VERBS (Phase 2, Model B; ADR-0007). Pass the NAMES of the
+ * hand verbs the served process loaded as `handVerbs`; each is attached to the
+ * returned `page` as a dynamic method forwarding over the RPC via
+ * {@link callHandVerb}, so the agent gains those tools WITHOUT ever holding a
+ * live page handle. They are NOT on the seam `WebHandsPage` type (the seam knows only
+ * the eight built-ins), so a caller reaches them through a cast, exactly as a
+ * third-party hand verb is reached on the in-process composed page. The result
+ * crosses the wire as a serializable value and a page/in-hand throw rejects
+ * faithfully, the same contract as the built-in verbs.
  */
-export function connectRemoteSession(baseUrl: string): Session {
+export function connectRemoteSession(
+	baseUrl: string,
+	handVerbs: readonly string[] = [],
+): Session {
 	const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
 
 	const send = async (request: SessionRpcRequest): Promise<unknown> => {
@@ -56,11 +70,35 @@ export function connectRemoteSession(baseUrl: string): Session {
 		throw new Error(reply.error);
 	};
 
+	let resolveClosed!: () => void;
+	const closedSignal = new Promise<void>((resolve) => {
+		resolveClosed = resolve;
+	});
+
+	const page = makeRpcPage(send);
+	// Attach each loaded hand verb as a dynamic method that forwards over the same
+	// RPC `send`. The seam `WebHandsPage` type names only the built-ins, so these live on
+	// the runtime object alongside them (mirroring how a hand verb composes into
+	// the in-process page object); callers reach them through a cast.
+	const pageWithHands = page as unknown as Record<string, unknown>;
+	for (const name of handVerbs) {
+		pageWithHands[name] = (...args: readonly unknown[]): Promise<unknown> =>
+			callHandVerb(send, name, ...args);
+	}
+
 	return {
-		page: makeRpcPage(send),
+		page,
 		async close() {
-			// Intentionally a no-op: the served process owns the session's lifetime
-			// (see this module's overview). Teardown is the explicit `stop` verb.
+			// Intentionally a no-op against the SERVER: the served process owns the
+			// session's lifetime (see this module's overview). Teardown is the
+			// explicit `stop` verb. We still resolve the local close signal so a
+			// caller awaiting waitForClose() on this client handle unblocks.
+			resolveClosed();
+		},
+		waitForClose(): Promise<void> {
+			// A client never waits on the user closing the window — that is the
+			// server's concern; this resolves on a local close() call.
+			return closedSignal;
 		},
 	};
 }