@webhands/core 0.1.0 → 1.0.0

package/src/session-rpc.ts

@@ -4,12 +4,12 @@ import {
 	type Snapshot,
 	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
@@ -17,11 +17,35 @@ 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. */
@@ -29,6 +53,15 @@ export const SESSION_RPC_PATH = '/session/call';
 
 /** A single verb call to run against the served live page. */
 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}
 	| {readonly verb: 'snapshot'; readonly full?: boolean}
 	| {readonly verb: 'click'; readonly locator: string}
@@ -38,6 +71,25 @@ export type SessionRpcRequest =
 	| {readonly verb: 'cookies'}
 	| {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
@@ -49,7 +101,7 @@ export type SessionRpcResponse =
 	| {readonly ok: false; 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.
@@ -59,7 +111,7 @@ export type SessionRpcResponse =
  * branded-string contract holds.
  */
 export async function applySessionRpc(
-	page: Page,
+	page: WebHandsPage,
 	request: SessionRpcRequest,
 ): Promise<unknown> {
 	switch (request.verb) {
@@ -84,11 +136,46 @@ export async function applySessionRpc(
 		case 'setCookies':
 			await page.setCookies(request.cookies);
 			return undefined;
+		case 'hand':
+			return applyHandVerb(page, request);
+	}
+}
+
+/**
+ * Invoke a dynamically-loaded hand verb by name against the live composed page.
+ *
+ * The composed {@link WebHandsPage} carries the hand's verbs at runtime (the host merged
+ * them in by name alongside the built-ins, see `composePage`), even though the
+ * seam `WebHandsPage` TYPE only names the eight built-ins. We therefore look the verb up
+ * on the page object as a runtime method and invoke it with the request's args.
+ * An unknown name is a faithful error (the hand was not loaded / named that
+ * verb), surfaced the same way a page-side throw is so the client rejects.
+ *
+ * The result is returned as-is: the serializable-only boundary is enforced by
+ * convention + types on the hand author, NOT a runtime clone here (a blanket
+ * clone would corrupt legitimate in-process Model A returns; see this module's
+ * overview). What the hand returns is what the wire carries back; the JSON
+ * framing in the server handler is the only encoding applied.
+ */
+async function applyHandVerb(
+	page: WebHandsPage,
+	request: SessionRpcHandRequest,
+): Promise<unknown> {
+	const verb = (page as unknown as Record<string, unknown>)[request.name];
+	if (typeof verb !== 'function') {
+		throw new Error(
+			`no such hand verb '${request.name}' on the live page ` +
+				`(is the hand loaded and named in config?)`,
+		);
 	}
+	return (verb as (...args: readonly unknown[]) => unknown).call(
+		page,
+		...request.args,
+	);
 }
 
 /**
- * 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
@@ -98,7 +185,7 @@ export async function applySessionRpc(
  */
 export function makeRpcPage(
 	send: (request: SessionRpcRequest) => Promise<unknown>,
-): Page {
+): WebHandsPage {
 	return {
 		async navigate(url) {
 			await send({verb: 'navigate', url});
@@ -130,6 +217,29 @@ export function makeRpcPage(
 	};
 }
 
+/**
+ * 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 async function callHandVerb(
+	send: (request: SessionRpcRequest) => Promise<unknown>,
+	name: string,
+	...args: readonly unknown[]
+): Promise<unknown> {
+	return send({verb: 'hand', name, args});
+}
+
 /**
  * Re-brand a {@link WaitCondition} that arrived as plain JSON: only the
  * `locator` form carries a branded string, which JSON flattens to a plain

package/src/stub-transport.ts

@@ -1,7 +1,7 @@
 import type {
 	Cookie,
 	OpenTarget,
-	Page,
+	WebHandsPage,
 	Session,
 	Snapshot,
 	SnapshotOptions,
@@ -13,7 +13,7 @@ import type {
  * A record of one verb call against the stub, for assertions in seam tests.
  */
 export interface StubCall {
-	readonly verb: keyof Page;
+	readonly verb: keyof WebHandsPage;
 	readonly args: readonly unknown[];
 }
 
@@ -37,6 +37,11 @@ export class StubTransport implements Transport {
 		const calls = this.calls;
 		let closed = false;
 
+		let resolveClosed!: () => void;
+		const closedSignal = new Promise<void>((resolve) => {
+			resolveClosed = resolve;
+		});
+
 		const ensureOpen = () => {
 			if (closed) {
 				throw new Error('session is closed');
@@ -48,7 +53,7 @@ export class StubTransport implements Transport {
 				? `stub://launch/${target.profile}`
 				: `stub://attach/${target.endpoint}`;
 
-		const page: Page = {
+		const page: WebHandsPage = {
 			async navigate(to: string): Promise<void> {
 				ensureOpen();
 				calls.push({verb: 'navigate', args: [to]});
@@ -93,7 +98,14 @@ export class StubTransport implements Transport {
 		return {
 			page,
 			async close(): Promise<void> {
+				if (closed) {
+					return;
+				}
 				closed = true;
+				resolveClosed();
+			},
+			waitForClose(): Promise<void> {
+				return closedSignal;
 			},
 		};
 	}