@svatah/yam-surface

The published AgentSurface interface, adapter registry and wire schemas

• Source: packages/surface · README: packages/surface/README.md
• Install: npm install @svatah/yam-surface
• Version 0.1.0 · Apache-2.0

Exports

Export	Kind	Signature
ActArgs	typealias	type ActArgs = z.infer<typeof actArgsSchema>;
actArgsSchema	variable	actArgsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>
ActionabilityError	class	export class ActionabilityError extends SurfaceError	The element was found but was not in a state that permits the action.
ActResult	typealias	type ActResult = z.infer<typeof actResultSchema>;
actResultSchema	variable	actResultSchema: z.ZodObject<
adapterDriver	function	export function adapterDriver(name: string): AdapterDriver | undefined	What name needs installed, when it needs anything.
AdapterDriver	interface	export interface AdapterDriver	What an adapter needs installed before it can drive anything (PK-03).
adapterFactory	function	export function adapterFactory(name: string): AdapterFactory | undefined	The factory registered under a name, or undefined.
AdapterFactory	typealias	export type AdapterFactory = (config: Config) => AgentSurface | Promise<AgentSurface>;	Adapter registration and selection (LLD §2.4, REQ-SURF-2).
AgentSurface	interface	export interface AgentSurface	The agent surface (LLD §2.1, REQ-SURF-1).
ApiRequest	typealias	type ApiRequest = z.infer<typeof apiRequestSchema>;
ApiResponse	typealias	type ApiResponse = z.infer<typeof apiResponseSchema>;
APPIUM_ANDROID_ROLE_MAP	variable	APPIUM_ANDROID_ROLE_MAP: Readonly<Record<string, string>>	Appium native Android class → ARIA role (REQ-ADP-5).
ATSPI_ROLE_MAP	variable	ATSPI_ROLE_MAP: Readonly<Record<string, string>>	AT-SPI role names, onto the same vocabulary (T23, SF-23).
AX_ROLE_MAP	variable	AX_ROLE_MAP: Readonly<Record<string, string>>	macOS Accessibility AXRole → ARIA role (REQ-ADP-7).
AX_WINDOW_CHROME_SUBROLES	variable	AX_WINDOW_CHROME_SUBROLES: ReadonlySet<string> = new Set([	The window's own buttons — close, minimise, zoom, full screen, collapse.
buildSnapshot	function	export function buildSnapshot(	Assemble a Snapshot from its nodes: renders the text and fills in the estimate.
Candidate	typealias	type Candidate = z.infer<typeof candidateSchema>;
Capabilities	typealias	type Capabilities = z.infer<typeof capabilitiesSchema>;
capabilitiesSchema	variable	capabilitiesSchema: z.ZodObject<
CAPABILITY_FLAGS	variable	CAPABILITY_FLAGS: readonly ["dialogs", "frames", "windows", "upload", "drag", "trace", "webmcp", "screenshot", "restore", "pick", "observe"]
CapabilityFlag	typealias	type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];
capabilityForAction	function	export function capabilityForAction(action: SurfaceAction): keyof Capabilities | undefined	The capability an action requires, or undefined when every adapter must support it.
CheckError	class	export class CheckError extends SurfaceError	A check() predicate did not hold. Maps to the assertion failure class.
CheckResult	typealias	type CheckResult = z.infer<typeof checkResultSchema>;
checkResultSchema	variable	checkResultSchema: z.ZodObject<
CheckSubject	typealias	type CheckSubject = z.infer<typeof checkSubjectSchema>;
clearAdapters	function	export function clearAdapters(): void	Drop every registration. For tests and for the REPL's session teardown.
createSurface	function	export async function createSurface(config: Config): Promise<AgentSurface>	Build the surface the configuration selects (LLD §2.4).
DataError	class	export class DataError extends SurfaceError	A value was missing or of the wrong type (type validation, {data.*} lookups).
DialogError	class	export class DialogError extends SurfaceError	A dialog was expected and absent, unexpected and present, or could not be handled.
ElementDescription	typealias	type ElementDescription = z.infer<typeof elementDescriptionSchema>;
elementDescriptionSchema	variable	elementDescriptionSchema: z.ZodObject<	What describe(ref) returns: everything candidate synthesis and fingerprinting
estimateTokens	function	export function estimateTokens(text: string): number	A rough token estimate for Snapshot.tokensEstimate, used to keep grounding
executableOf	function	export function executableOf(launch: LaunchConfig, platform: string): string | undefined	The executable a pgrep -f / taskkill addresses, for either shape.
failureClassOf	function	export function failureClassOf(error: unknown): FailureClass	The failure class for any thrown value (LLD §8.4).
FALLBACK_ROLE	variable	FALLBACK_ROLE = "generic"	What an unmapped source role becomes.
hasAdapter	function	export function hasAdapter(name: string): boolean
INTERACTIVE_ROLES	variable	INTERACTIVE_ROLES: ReadonlySet<string> = new Set([	The roles that are worth acting on (LLD §2.2, §11).
isInteractiveRole	function	export function isInteractiveRole(role: string): boolean
isWindowChrome	function	export function isWindowChrome(node:	Is this snapshot node one of the window manager's own controls?
launchApplication	function	export function launchApplication(	Start the application.
LaunchConfig	interface	export interface LaunchConfig	Where the application is and how to start it (config.app.launch).
lengthBucket	function	export function lengthBucket(value: string | undefined): string	Names collapse to a length bucket: 0, 1-8, 9-32, 33+ (LLD §6.2).
LifecycleStep	interface	export interface LifecycleStep	What ran, so a caller can say what it did and a test can see it.
listAdapters	function	export function listAdapters(): string[]	Every registered adapter name, sorted.
LOCATE_RETURN_MARGIN_MS	variable	LOCATE_RETURN_MARGIN_MS = 250	How long an adapter's locate may keep asking.
locateDeadline	function	export function locateDeadline(candidateTimeoutMs: number | undefined, now = Date.now()): number	The instant an adapter's retrying locate must answer by, given the
LocateError	class	export class LocateError extends SurfaceError	A candidate matched no element, or matched more than one where exactly one was
missingCapabilities	function	export function missingCapabilities(	The capabilities a set of actions needs but the adapter lacks. Empty means the
NavigationError	class	export class NavigationError extends SurfaceError	Navigation failed, timed out, or landed somewhere unexpected.
NO_CAPABILITIES	variable	NO_CAPABILITIES: Capabilities	All capability flags default to false, so an adapter opts in to what it supports.
NODE_STATES	variable	NODE_STATES: readonly ["disabled", "checked", "unchecked", "selected", "expanded", "collapsed", "focused", "required", "hidden", "readonly"]
NodeState	typealias	type NodeState = z.infer<typeof nodeStateSchema>;
normalisedRoles	function	export function normalisedRoles(): string[]	Every ARIA role any table maps onto, sorted. Useful for conformance assertions.
normaliseRole	function	export function normaliseRole(map: RoleMapName, sourceRole: string): string	Map one source role onto the ARIA vocabulary, falling back to generic.
ObservedEvent	typealias	export type ObservedEvent	One thing a person did in the driven session (Draft 2.23, REQ-REC-13).
Predicate	typealias	type Predicate = z.infer<typeof predicateSchema>;
processIdsOf	function	export function processIdsOf(	The process ids of this executable, right now.
quitApplication	function	export async function quitApplication(	Stop it: the graceful route, then a signal, then a harder one.
QuitConfig	interface	export interface QuitConfig	How to stop it (config.app.quit).
ReadKind	typealias	type ReadKind = z.infer<typeof readKindSchema>;
Ref	typealias	type Ref = z.infer<typeof refSchema>;
registerAdapter	function	export function registerAdapter(name: string, factory: AdapterFactory, driver?: AdapterDriver): void	Register an adapter under a name. Registering the same name twice is an error:
renderForHash	function	export function renderForHash(nodes: readonly SnapshotNode[]): string	The canonical rendering the hash is taken over: one line per node, indented by
renderNode	function	export function renderNode(node: SnapshotNode, options: RenderOptions = {}): string	Render one node, without its children.
RenderOptions	interface	export interface RenderOptions
renderSnapshot	function	export function renderSnapshot(	Render a whole snapshot. Nodes are emitted in the order the adapter produced
REQUIRED_SURFACE_METHODS	variable	REQUIRED_SURFACE_METHODS = SURFACE_METHODS.filter(	The methods every adapter must implement; trace, request, pick and observe are optional.
ROLE_MAPS	variable	ROLE_MAPS	The published mapping tables, keyed by the adapter family they belong to.
RoleMapName	typealias	export type RoleMapName = keyof typeof ROLE_MAPS;
Runner	interface	export interface Runner	The commands this module runs. Injected, so every path above is testable.
ScriptError	class	export class ScriptError extends SurfaceError	An evaluate or an injected script threw.
SessionError	class	export class SessionError extends SurfaceError	The session could not be opened, was lost, or the driven process crashed.
SessionInit	typealias	type SessionInit = z.infer<typeof sessionInitSchema>;
sessionInitSchema	variable	sessionInitSchema: z.ZodObject<
SessionState	typealias	type SessionState = z.infer<typeof sessionStateSchema>;
sessionStateSchema	variable	sessionStateSchema: z.ZodObject<	The restorable subset of session state (LLD §2.1). It is what a checkpoint
Snapshot	typealias	type Snapshot = z.infer<typeof snapshotSchema>;
SnapshotNode	typealias	type SnapshotNode = z.infer<typeof snapshotNodeSchema>;
snapshotNodeSchema	variable	snapshotNodeSchema: z.ZodObject<
snapshotSchema	variable	snapshotSchema: z.ZodObject<
structuralHash	function	export function structuralHash(nodes: readonly SnapshotNode[]): string	sha256 of renderForHash, hex encoded.
SURFACE_ACTIONS	variable	SURFACE_ACTIONS: readonly SurfaceAction[]
SURFACE_ERRORS	variable	SURFACE_ERRORS = [	Every surface error class, in the order LLD §2.3 lists them.
SURFACE_METHODS	variable	SURFACE_METHODS = [	Every method name on AgentSurface, required first, then the optional ones.
SurfaceAction	typealias	type SurfaceAction = Exclude<Action, (typeof SURFACE_ONLY_EXCLUSIONS)[number]>;
surfaceActionSchema	variable	surfaceActionSchema: z.ZodEnum<["navigate", "back", "forward", "refresh", "click", "doubleClick", "rightClick", "hover", "hoverAndClick", "pressAndHold", "relea
surfaceActMessageSchema	variable	surfaceActMessageSchema: z.ZodObject<	surface.act.schema.json — request and response of act().
surfaceCapabilitiesMessageSchema	variable	surfaceCapabilitiesMessageSchema: z.ZodObject<	surface.capabilities.schema.json — the descriptor an adapter publishes.
surfaceCheckMessageSchema	variable	surfaceCheckMessageSchema: z.ZodObject<	surface.check.schema.json — request and response of check().
SurfaceError	class	export abstract class SurfaceError extends Error	The typed errors adapters throw (LLD §2.3).
SurfaceKind	typealias	type SurfaceKind = z.infer<typeof surfaceKindSchema>;
surfaceLocateMessageSchema	variable	surfaceLocateMessageSchema: z.ZodObject<	surface.locate.schema.json — candidate in, references out (used by the resolver).
SurfaceMethod	typealias	export type SurfaceMethod = (typeof SURFACE_METHODS)[number];
surfaceReadMessageSchema	variable	surfaceReadMessageSchema: z.ZodObject<	surface.read.schema.json — request and response of read().
surfaceSnapshotMessageSchema	variable	surfaceSnapshotMessageSchema: z.ZodObject<	surface.snapshot.schema.json — request and response of snapshot().
systemRunner	variable	systemRunner: Runner
TimeoutError	class	export class TimeoutError extends SurfaceError	An operation exceeded its configured timeout.
UIA_ROLE_MAP	variable	UIA_ROLE_MAP: Readonly<Record<string, string>>	Windows UI Automation ControlType → ARIA role (REQ-ADP-6).
UIA_WINDOW_CHROME_IDS	variable	UIA_WINDOW_CHROME_IDS: ReadonlySet<string> = new Set([	What Windows calls the same three, as AutomationIds.
unregisterAdapter	function	export function unregisterAdapter(name: string): boolean	Remove a registration. Returns false when the name was not registered.
waitFor	function	export async function waitFor(	Wait for a condition, and say how long it took.