@webhands/core 0.1.0 → 0.2.0

package/dist/playwright-launch-transport.js

@@ -1,6 +1,7 @@
 import { stat } from 'node:fs/promises';
-import { chromium, errors as pwErrors, } from 'playwright';
+import { chromium } from 'playwright';
 import { MissingBrowserBinaryError, MissingProfileError } from './errors.js';
+import { composeWithHands } from './hand-host.js';
 import { resolveProfileLocation, } from './profile-location.js';
 /**
  * The v1 concrete transport: a Playwright browser the controller LAUNCHES
@@ -21,13 +22,19 @@ import { resolveProfileLocation, } from './profile-location.js';
  */
 export class PlaywrightLaunchTransport {
     #location;
+    #hands;
     /**
      * @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.
      */
-    constructor(location = {}) {
+    constructor(location = {}, hands = []) {
         this.#location = location;
+        this.#hands = hands;
     }
     async open(target) {
         if (target.mode !== 'launch') {
@@ -61,7 +68,7 @@ export class PlaywrightLaunchTransport {
         // 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);
     }
 }
 /** True iff `path` exists and is a directory. */
@@ -86,220 +93,60 @@ function isMissingBrowserBinary(cause) {
         /please run the following command to download new browsers/i.test(message) ||
         /playwright install/i.test(message));
 }
-/** Wrap a live Playwright persistent context into the seam's {@link Session}. */
-function makeSession(context, pwPage) {
+/**
+ * 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, pwPage, extraHands) {
     let closed = false;
     const ensureOpen = () => {
         if (closed) {
             throw new Error('session is closed');
         }
     };
-    const page = {
-        async navigate(url) {
-            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) {
-            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) {
-            ensureOpen();
-            await clickLocator(pwPage, t);
-        },
-        async type(t, text) {
-            ensureOpen();
-            await resolveLocator(pwPage, t).fill(text);
-        },
-        async eval(expression) {
-            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) {
-            ensureOpen();
-            await waitFor(pwPage, condition);
-        },
-        async cookies() {
-            ensureOpen();
-            const raw = await context.cookies();
-            return raw.map(toSeamCookie);
-        },
-        async setCookies(cookies) {
-            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;
+    const closedSignal = new Promise((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 = { pwPage, context, ensureOpen };
+    const { page, dispose: disposeHands } = composeWithHands(handContext, extraHands);
     return {
         page,
         async close() {
-            if (closed)
+            if (closed) {
                 return;
-            closed = true;
+            }
+            // 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() {
+            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, condition) {
-    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, expression) {
-    // eslint-disable-next-line no-new-func
-    const factory = new Function('page', 'p', `return (${expression});`);
-    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, expression) {
-    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) {
-    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) {
-    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,
     };
 }
 //# sourceMappingURL=playwright-launch-transport.js.map

package/dist/playwright-launch-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}

package/dist/remote-session.d.ts

@@ -4,7 +4,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
@@ -17,6 +17,16 @@ 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 declare function connectRemoteSession(baseUrl: string): Session;
+export declare function connectRemoteSession(baseUrl: string, handVerbs?: readonly string[]): Session;
 //# sourceMappingURL=remote-session.d.ts.map

package/dist/remote-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-session.d.ts","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsC7D"}
+{"version":3,"file":"remote-session.d.ts","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAAO,GAC/B,OAAO,CA8DT"}

package/dist/remote-session.js

@@ -1,10 +1,10 @@
-import { makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.js';
+import { callHandVerb, makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.js';
 /**
  * A client-side {@link Session} that drives a session living in a SEPARATE
  * 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
@@ -17,8 +17,18 @@ import { makeRpcPage, SESSION_RPC_PATH, } from './session-rpc.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) {
+export function connectRemoteSession(baseUrl, handVerbs = []) {
     const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
     const send = async (request) => {
         let res;
@@ -46,11 +56,32 @@ export function connectRemoteSession(baseUrl) {
         // process boundary.
         throw new Error(reply.error);
     };
+    let resolveClosed;
+    const closedSignal = new Promise((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;
+    for (const name of handVerbs) {
+        pageWithHands[name] = (...args) => 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() {
+            // 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;
         },
     };
 }

package/dist/remote-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote-session.js","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,gBAAgB,GAGhB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IACnD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAE/D,MAAM,IAAI,GAAG,KAAK,EAAE,OAA0B,EAAoB,EAAE;QACnE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;gBAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC7B,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,mEAAmE;YACnE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CACd,yCAAyC,OAAO,KAAK,OAAO,EAAE,CAC9D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACvD,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,oBAAoB;QACpB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,OAAO;QACN,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC;QACvB,KAAK,CAAC,KAAK;YACV,wEAAwE;YACxE,sEAAsE;QACvE,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"remote-session.js","sourceRoot":"","sources":["../src/remote-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,WAAW,EACX,gBAAgB,GAGhB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAe,EACf,YAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAE/D,MAAM,IAAI,GAAG,KAAK,EAAE,OAA0B,EAAoB,EAAE;QACnE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;gBAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC7B,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,mEAAmE;YACnE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CACd,yCAAyC,OAAO,KAAK,OAAO,EAAE,CAC9D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACvD,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,oBAAoB;QACpB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,IAAI,aAA0B,CAAC;IAC/B,MAAM,YAAY,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClD,aAAa,GAAG,OAAO,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,sFAAsF;IACtF,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,aAAa,GAAG,IAA0C,CAAC;IACjE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC9B,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAwB,EAAoB,EAAE,CACvE,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,OAAO;QACN,IAAI;QACJ,KAAK,CAAC,KAAK;YACV,wEAAwE;YACxE,mEAAmE;YACnE,qEAAqE;YACrE,iEAAiE;YACjE,aAAa,EAAE,CAAC;QACjB,CAAC;QACD,YAAY;YACX,oEAAoE;YACpE,2DAA2D;YAC3D,OAAO,YAAY,CAAC;QACrB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/seam.d.ts

@@ -65,7 +65,7 @@ export interface Cookie {
     readonly secure?: boolean;
     readonly sameSite?: 'Strict' | 'Lax' | 'None';
 }
-/** What to wait for in the {@link Page.wait} verb. */
+/** What to wait for in the {@link WebHandsPage.wait} verb. */
 export type WaitCondition = {
     readonly kind: 'timeout';
     readonly ms: number;
@@ -87,7 +87,7 @@ export type WaitCondition = {
  *   `needsAnswers` Q3): default is the accessibility view, `--full` is raw DOM.
  */
 export type SnapshotView = 'accessibility' | 'full';
-/** Options for the {@link Page.snapshot} verb. */
+/** Options for the {@link WebHandsPage.snapshot} verb. */
 export interface SnapshotOptions {
     /**
      * When `true`, return the raw DOM (`view: 'full'`) instead of the default
@@ -124,7 +124,7 @@ export interface Snapshot {
  * The page-level verb surface. One method per verb in the domain glossary.
  * All element addressing flows through {@link LocatorString}.
  */
-export interface Page {
+export interface WebHandsPage {
     /** Navigate the active page to a URL and let it settle. */
     navigate(url: string): Promise<void>;
     /**
@@ -187,16 +187,24 @@ export interface Page {
     setCookies(cookies: readonly Cookie[]): Promise<void>;
 }
 /**
- * A live browser session owning one active {@link Page}. The session lifetime
+ * A live browser session owning one active {@link WebHandsPage}. The session lifetime
  * spans from {@link Transport.open} to {@link Session.close}; it is the unit a
  * long-lived controller process keeps between CLI invocations (PRD
  * "session/daemon question").
  */
 export interface Session {
     /** The active page the verbs act on. */
-    readonly page: Page;
+    readonly page: WebHandsPage;
     /** Tear down the session and release the underlying browser resources. */
     close(): Promise<void>;
+    /**
+     * Resolve when the session is closed — either by the USER closing the browser
+     * window/context, or by a {@link Session.close} call. This is what lets a
+     * headed flow (notably `setup-profile`) HOLD the window open and block until
+     * the human is done, instead of tearing it down immediately. Resolves once
+     * (idempotent); resolves immediately if the session is already closed.
+     */
+    waitForClose(): Promise<void>;
 }
 /**
  * The transport seam. A `Transport` (a.k.a. driver) knows how to OPEN a

package/dist/seam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"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"}

package/dist/session-rpc.d.ts

@@ -1,9 +1,9 @@
 import { type Cookie, type WaitCondition } from './seam.js';
-import type { Page } from './seam.js';
+import type { WebHandsPage } from './seam.js';
 /**
  * The wire protocol for driving the long-lived session over HTTP (ADR-0005).
  *
- * The served process holds ONE live {@link Page} in memory; a thin client verb
+ * The served process holds ONE live {@link WebHandsPage} in memory; a thin client verb
  * cannot hold a JS reference to it across the process boundary, so each verb
  * call is sent as a small JSON request to the server, which runs it against its
  * live page and returns the result. This module is the SINGLE source of truth
@@ -11,16 +11,46 @@ import type { Page } from './seam.js';
  * client proxy so they cannot drift (mirrors how `serializeCookies` is shared
  * by the cookies verb and its test).
  *
- * It is a thin transport detail, NOT a second verb surface: every request maps
- * 1:1 to a {@link Page} method, and the seam's verb semantics (ADR-0003/0004)
- * are unchanged. The {@link LocatorString} brand and the structured
- * {@link WaitCondition} cross as plain JSON and are re-branded on the server
- * with {@link locator}; no Playwright/CDP type is ever named here.
+ * It is a thin transport detail, NOT a second verb surface: every built-in
+ * request maps 1:1 to a {@link WebHandsPage} method, and the seam's verb semantics
+ * (ADR-0003/0004) are unchanged. The {@link LocatorString} brand and the
+ * structured {@link WaitCondition} cross as plain JSON and are re-branded on the
+ * server with {@link locator}; no Playwright/CDP type is ever named here.
+ *
+ * THIRD-PARTY HAND VERBS (Phase 2, Model B of the "hands" prd; ADR-0007). The
+ * eight built-in verbs stay a CLOSED union (the 1:1 source of truth above). A
+ * dynamically-loaded hand contributes a verb whose name `core` does NOT know at
+ * compile time, so it cannot be a named member of that closed union without
+ * re-meaning "closed". Instead it crosses as a SINGLE generic
+ * {@link SessionRpcHandRequest} variant (`{verb: 'hand', name, args}`) that
+ * names the contributed verb at runtime and carries its arguments. This is the
+ * exact wire parallel of how a hand verb composes into the page object: by name,
+ * dynamically, alongside the typed built-ins. The agent thereby gains a new tool
+ * over the wire WITHOUT ever holding a live page handle.
+ *
+ * SERIALIZATION BOUNDARY (the load-bearing rule; prd's resolved Q3). A hand
+ * verb's result crosses this RPC, so it MUST be serializable under the same
+ * structured-clone contract `eval` documents (see {@link WebHandsPage.eval}): richer
+ * than JSON, but a value with no transferable form does not round-trip. This is
+ * enforced by CONVENTION + TYPES (a hand author returns serializable values),
+ * NOT a blanket runtime clone here — a blanket clone would corrupt legitimate
+ * in-process (Model A) returns, where a hand may pass/return live Playwright
+ * handles within a single in-process call chain. A host-side runtime clone of
+ * agent-verb results is available HARDENING for untrusted hands, not built here.
+ * A page/in-hand throw REJECTS faithfully on the client exactly as the `eval`
+ * path already does (the server maps it to an `ok: false` reply carrying the
+ * message; the client re-throws a faithful `Error`).
  */
 /** The path the session RPC is served under, below the server's base URL. */
 export declare const SESSION_RPC_PATH = "/session/call";
 /** A single verb call to run against the served live page. */
-export type SessionRpcRequest = {
+export type SessionRpcRequest = SessionRpcBuiltInRequest | SessionRpcHandRequest;
+/**
+ * The CLOSED union of webhands' eight built-in verbs. Each variant maps 1:1 to a
+ * {@link WebHandsPage} method in {@link applySessionRpc}; this is the single source of
+ * truth for the built-in verb surface, shared verbatim by server and client.
+ */
+export type SessionRpcBuiltInRequest = {
     readonly verb: 'navigate';
     readonly url: string;
 } | {
@@ -45,6 +75,24 @@ export type SessionRpcRequest = {
     readonly verb: 'setCookies';
     readonly cookies: readonly Cookie[];
 };
+/**
+ * The OPEN escape for a dynamically-loaded third-party hand verb (Phase 2,
+ * Model B; ADR-0007). Unlike the closed built-in union, `core` does not know the
+ * verb's name at compile time, so it is carried at runtime: `name` is the
+ * contributed verb's plain name (exactly as it composed into the page object,
+ * not namespaced — a hand may even deliberately override a built-in, the
+ * operator's choice per ADR-0007) and `args` are its JSON arguments.
+ *
+ * The returned value and any thrown error obey the same serialization +
+ * rejection contract as `eval` (see this module's overview and {@link WebHandsPage.eval}).
+ */
+export interface SessionRpcHandRequest {
+    readonly verb: 'hand';
+    /** The hand-contributed verb's name (as it composed into the page object). */
+    readonly name: string;
+    /** The verb's arguments, carried as plain JSON (must be serializable). */
+    readonly args: readonly unknown[];
+}
 /**
  * The server's reply to a {@link SessionRpcRequest}. `ok: true` carries the
  * verb's return value (for verbs that return data); `ok: false` carries the
@@ -59,7 +107,7 @@ export type SessionRpcResponse = {
     readonly error: string;
 };
 /**
- * Run one {@link SessionRpcRequest} against a live {@link Page}, returning the
+ * Run one {@link SessionRpcRequest} against a live {@link WebHandsPage}, returning the
  * value the wire should carry back. The server's HTTP handler is just this plus
  * JSON framing; keeping the dispatch here (not inline in the handler) means the
  * verb-to-page mapping is in one place and unit-testable without HTTP.
@@ -68,9 +116,9 @@ export type SessionRpcResponse = {
  * locator with {@link locator} before handing it to the page so the seam's
  * branded-string contract holds.
  */
-export declare function applySessionRpc(page: Page, request: SessionRpcRequest): Promise<unknown>;
+export declare function applySessionRpc(page: WebHandsPage, request: SessionRpcRequest): Promise<unknown>;
 /**
- * A {@link Page} whose verbs forward to a server via the supplied transport.
+ * A {@link WebHandsPage} whose verbs forward to a server via the supplied transport.
  *
  * Used by the client-side proxy (see `remote-session.ts`): each verb builds a
  * {@link SessionRpcRequest}, hands it to `send`, and shapes the reply back into
@@ -78,5 +126,21 @@ export declare function applySessionRpc(page: Page, request: SessionRpcRequest):
  * the verb-to-request mapping (the other half of {@link applySessionRpc}) in
  * one place so request and response shapes cannot drift between the two sides.
  */
-export declare function makeRpcPage(send: (request: SessionRpcRequest) => Promise<unknown>): Page;
+export declare function makeRpcPage(send: (request: SessionRpcRequest) => Promise<unknown>): WebHandsPage;
+/**
+ * Invoke a dynamically-loaded hand verb over the session RPC by name (Phase 2,
+ * Model B; ADR-0007). The client-side mirror of {@link applyHandVerb}: it builds
+ * the single generic {@link SessionRpcHandRequest} and hands it to the SAME
+ * `send` the built-in verbs use, so request/response shapes cannot drift.
+ *
+ * This is how the agent gains a new tool over the wire WITHOUT holding a live
+ * page handle: it names the contributed verb and passes serializable args; the
+ * server runs the hand against its own live page and returns a serializable
+ * result. A page/in-hand throw rejects faithfully (the `send` re-throws the
+ * server's error message), exactly as the `eval` path does.
+ *
+ * The result type is `unknown` because the hand decides the shape; callers
+ * narrow it (mirrors {@link WebHandsPage.eval}).
+ */
+export declare function callHandVerb(send: (request: SessionRpcRequest) => Promise<unknown>, name: string, ...args: readonly unknown[]): Promise<unknown>;
 //# sourceMappingURL=session-rpc.d.ts.map