@blario/react-native 0.0.0 → 0.1.0

package/src/actions/scrolling.ts

@@ -0,0 +1,112 @@
+import { measureHost } from '../host/measure.ts';
+import { type Band, scrollDeltaIntoBand } from '../host/rect.ts';
+import { scrollInstanceOf } from '../snapshot/classify.ts';
+import { maxScrollOffsetOf, measureScrollGeometry, scrollOffsetOf, type ScrollGeometry, viewportExtentOf } from '../snapshot/scroll.ts';
+import { failed, failedFromException, succeeded } from './result.ts';
+import type { ResolvedTarget } from './target.ts';
+import type { AgentAction, HandlerResult } from './types.ts';
+
+type ScrollAction = Extract<AgentAction, { type: 'scroll' }>;
+
+const PAGE_FRACTION = 0.8;
+const VISIBLE_MARGIN = 24;
+const MOVEMENT_TOLERANCE = 1;
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(Math.max(value, minimum), maximum);
+}
+
+function applyOffset(target: ResolvedTarget, geometry: ScrollGeometry, offset: number, animated: boolean): HandlerResult {
+  const instance = scrollInstanceOf(target.fiber);
+  if (instance === null) {
+    return failed('element_not_interactable', 'the scroll container has no scrollTo');
+  }
+  try {
+    instance.scrollTo(geometry.horizontal ? { x: offset, animated } : { y: offset, animated });
+    return succeeded();
+  } catch (error) {
+    return failedFromException(error);
+  }
+}
+
+export async function scrollContainer(target: ResolvedTarget, action: ScrollAction): Promise<HandlerResult> {
+  if (target.element.kind !== 'scroll') {
+    return failed('element_not_interactable', 'scroll needs a scroll container (scr-N)');
+  }
+  const geometry = await measureScrollGeometry(target.fiber);
+  if (geometry === null) {
+    return failed('element_not_found', 'the scroll container could not be measured');
+  }
+  const isHorizontalAction = action.direction === 'left' || action.direction === 'right';
+  if (isHorizontalAction !== geometry.horizontal) {
+    return failed('element_not_interactable', `the container scrolls ${geometry.horizontal ? 'horizontally' : 'vertically'}`);
+  }
+  const forward = action.direction === 'down' || action.direction === 'right';
+  const distance = action.amount ?? Math.round(viewportExtentOf(geometry) * PAGE_FRACTION);
+  const current = scrollOffsetOf(geometry);
+  const next = clamp(current + (forward ? distance : -distance), 0, maxScrollOffsetOf(geometry));
+  if (Math.abs(next - current) < MOVEMENT_TOLERANCE) {
+    return succeeded('already at the edge of the container');
+  }
+  return applyOffset(target, geometry, next, true);
+}
+
+function nearestScrollAncestor(target: ResolvedTarget): ResolvedTarget['fiber'] | null {
+  for (let index = target.ancestors.length - 1; index >= 0; index -= 1) {
+    const ancestor = target.ancestors[index];
+    if (ancestor !== undefined && scrollInstanceOf(ancestor) !== null) {
+      return ancestor;
+    }
+  }
+  return null;
+}
+
+function offsetDeltaToReveal(start: number, end: number, viewportStart: number, viewportEnd: number): number {
+  const startShortfall = start - (viewportStart + VISIBLE_MARGIN);
+  if (startShortfall < 0) {
+    return startShortfall;
+  }
+  const endOverflow = end - (viewportEnd - VISIBLE_MARGIN);
+  return endOverflow > 0 ? Math.min(endOverflow, startShortfall) : 0;
+}
+
+export async function scrollIntoView(target: ResolvedTarget, options: { animated: boolean } = { animated: true }): Promise<HandlerResult> {
+  const container = nearestScrollAncestor(target);
+  if (container === null || target.host === null) {
+    return succeeded('the element is not inside a scroll container');
+  }
+  const [geometry, rect] = await Promise.all([measureScrollGeometry(container), measureHost(target.host)]);
+  if (geometry === null || rect === null) {
+    return failed('element_not_found', 'the element or its scroll container could not be measured');
+  }
+  const { viewport, horizontal } = geometry;
+  const delta = horizontal
+    ? offsetDeltaToReveal(rect.x, rect.x + rect.width, viewport.x, viewport.x + viewport.width)
+    : offsetDeltaToReveal(rect.y, rect.y + rect.height, viewport.y, viewport.y + viewport.height);
+  if (Math.abs(delta) < MOVEMENT_TOLERANCE) {
+    return succeeded('the element is already in view');
+  }
+  const next = clamp(scrollOffsetOf(geometry) + delta, 0, maxScrollOffsetOf(geometry));
+  return applyOffset({ ...target, fiber: container }, geometry, next, options.animated);
+}
+
+export async function scrollIntoBand(target: ResolvedTarget, band: Band): Promise<HandlerResult> {
+  const container = nearestScrollAncestor(target);
+  if (container === null || target.host === null) {
+    return succeeded('the element is not inside a scroll container');
+  }
+  const [geometry, rect] = await Promise.all([measureScrollGeometry(container), measureHost(target.host)]);
+  if (geometry === null || rect === null) {
+    return failed('element_not_found', 'the element or its scroll container could not be measured');
+  }
+  if (geometry.horizontal) {
+    return succeeded('the container scrolls sideways');
+  }
+  const { viewport } = geometry;
+  const keepsInside = clamp(scrollDeltaIntoBand(rect, band), rect.y + rect.height - (viewport.y + viewport.height), rect.y - viewport.y);
+  const next = clamp(scrollOffsetOf(geometry) + keepsInside, 0, maxScrollOffsetOf(geometry));
+  if (Math.abs(next - scrollOffsetOf(geometry)) < MOVEMENT_TOLERANCE) {
+    return succeeded('the element is already in place');
+  }
+  return applyOffset({ ...target, fiber: container }, geometry, next, true);
+}

package/src/actions/services.ts

@@ -0,0 +1,24 @@
+import type { RegisteredElement } from '../snapshot/registry.ts';
+import type { CursorPort } from './landing.ts';
+import { NavigationDriver } from './navigation-driver.ts';
+import { TargetResolver, type TargetView } from './target.ts';
+
+export interface ReadingRequest extends TargetView {
+  text: string | null;
+}
+
+export interface ReadingPort {
+  read: (request: ReadingRequest) => Promise<boolean>;
+}
+
+export interface InputMemory {
+  last: RegisteredElement | null;
+}
+
+export interface ActionServices {
+  resolver: TargetResolver;
+  navigation: NavigationDriver;
+  reading: ReadingPort;
+  cursor: CursorPort;
+  inputMemory: InputMemory;
+}

package/src/actions/settle.ts

@@ -0,0 +1,40 @@
+export interface SettleOptions {
+  minWaitMs: number;
+  quietMs: number;
+  capMs: number;
+  pollMs: number;
+}
+
+export interface Clock {
+  now: () => number;
+  sleep: (milliseconds: number) => Promise<void>;
+}
+
+export const DEFAULT_SETTLE: SettleOptions = { minWaitMs: 300, quietMs: 150, capMs: 2000, pollMs: 75 };
+
+export const SYSTEM_CLOCK: Clock = {
+  now: () => Date.now(),
+  sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+};
+
+export async function waitForSettle(
+  sample: () => Promise<string>,
+  options: SettleOptions = DEFAULT_SETTLE,
+  clock: Clock = SYSTEM_CLOCK,
+): Promise<string> {
+  const startedAt = clock.now();
+  await clock.sleep(options.minWaitMs);
+  let latest = await sample();
+  let stableSince = clock.now();
+  while (clock.now() - startedAt < options.capMs) {
+    await clock.sleep(options.pollMs);
+    const current = await sample();
+    if (current !== latest) {
+      latest = current;
+      stableSince = clock.now();
+    } else if (clock.now() - stableSince >= options.quietMs) {
+      break;
+    }
+  }
+  return latest;
+}

package/src/actions/switch.ts

@@ -0,0 +1,31 @@
+import { isFunction } from '../fiber/narrow.ts';
+import { runBatched } from './batched.ts';
+import { checkInteractable } from './interaction-guards.ts';
+import { failed, failedFromException, succeeded } from './result.ts';
+import type { ResolvedTarget } from './target.ts';
+import type { HandlerResult } from './types.ts';
+
+export function toggleSwitch(target: ResolvedTarget, desired: boolean | null): HandlerResult {
+  if (target.element.kind !== 'switch') {
+    return failed('element_not_interactable', 'check needs a switch or checkbox');
+  }
+  const verdict = checkInteractable(target.fiber, target.ancestors);
+  if (!verdict.allowed) {
+    return failed('element_not_interactable', verdict.reason);
+  }
+  const onValueChange = target.props.onValueChange;
+  if (!isFunction(onValueChange)) {
+    return failed('element_not_interactable', 'the switch no longer has an onValueChange handler');
+  }
+  const current = target.props.value === true;
+  const next = desired ?? !current;
+  if (next === current) {
+    return succeeded(`already ${current ? 'on' : 'off'}`);
+  }
+  try {
+    runBatched(() => onValueChange(next));
+    return succeeded();
+  } catch (error) {
+    return failedFromException(error);
+  }
+}

package/src/actions/target.ts

@@ -0,0 +1,77 @@
+import { currentRootFiber, locateCurrent } from '../fiber/locate.ts';
+import { firstHostDescendant, propsOf } from '../fiber/reader.ts';
+import { collectText } from '../fiber/text.ts';
+import { explicitLabelOf, placeholderOf } from '../snapshot/properties.ts';
+import { borderRadiusOf } from '../host/border-radius.ts';
+import { measureHost } from '../host/measure.ts';
+import type { Band, Rect } from '../host/rect.ts';
+import type { Fiber, Props } from '../fiber/types.ts';
+import { ElementRegistry, type RegisteredElement } from '../snapshot/registry.ts';
+import { scrollIntoBand } from './scrolling.ts';
+
+export interface ResolvedTarget {
+  element: RegisteredElement;
+  fiber: Fiber;
+  ancestors: Fiber[];
+  props: Props;
+  host: Fiber | null;
+}
+
+export class TargetResolver {
+  constructor(
+    private readonly registry: ElementRegistry,
+    private readonly getAnchorFiber: () => Fiber | null,
+  ) {}
+
+  resolveAgentId(agentId: string): ResolvedTarget | null {
+    const element = this.registry.find(agentId);
+    return element === null ? null : this.resolveElement(element);
+  }
+
+  resolveElement(element: RegisteredElement): ResolvedTarget | null {
+    const anchor = this.getAnchorFiber();
+    const root = anchor === null ? null : currentRootFiber(anchor);
+    if (root === null) {
+      return null;
+    }
+    const located = locateCurrent(root, element.fiber);
+    if (located === null) {
+      return null;
+    }
+    return {
+      element,
+      fiber: located.fiber,
+      ancestors: located.ancestors,
+      props: propsOf(located.fiber),
+      host: firstHostDescendant(located.fiber),
+    };
+  }
+}
+
+export interface TargetView {
+  measure: () => Promise<Rect | null>;
+  radius: number;
+  reveal?: (band: Band) => Promise<void>;
+}
+
+export function measureTarget(target: ResolvedTarget): () => Promise<Rect | null> {
+  const host = target.host;
+  return host === null ? () => Promise.resolve(target.element.rect) : () => measureHost(host);
+}
+
+export function viewOf(target: ResolvedTarget): TargetView {
+  return {
+    measure: measureTarget(target),
+    radius: target.host === null ? 0 : borderRadiusOf(propsOf(target.host).style),
+    reveal: async (band) => {
+      await scrollIntoBand(target, band);
+    },
+  };
+}
+
+const NAME_LIMIT = 80;
+
+export function nameOf(target: ResolvedTarget): string | null {
+  const name = explicitLabelOf(target.props) ?? (collectText(target.fiber, NAME_LIMIT) || placeholderOf(target.props));
+  return name === null || name.length === 0 ? null : name.slice(0, NAME_LIMIT);
+}

package/src/actions/text-input.ts

@@ -0,0 +1,82 @@
+import { findNodeHandle, Platform, UIManager } from 'react-native';
+
+import { isFunction } from '../fiber/narrow.ts';
+import { propsOf } from '../fiber/reader.ts';
+import { hostInstanceOf } from '../host/instance.ts';
+import { runBatched } from './batched.ts';
+import { buildSubmitEvent, buildTextChangeEvent } from './events.ts';
+import { checkEditable } from './interaction-guards.ts';
+import { failed, failedFromException, succeeded } from './result.ts';
+import type { ActionServices } from './services.ts';
+import type { ResolvedTarget } from './target.ts';
+import type { AgentAction, HandlerResult } from './types.ts';
+
+type TypeAction = Extract<AgentAction, { type: 'type' }>;
+
+function currentTextOf(target: ResolvedTarget): string {
+  const { value, defaultValue } = target.props;
+  if (typeof value === 'string') {
+    return value;
+  }
+  return typeof defaultValue === 'string' ? defaultValue : '';
+}
+
+function isControlled(target: ResolvedTarget): boolean {
+  return typeof target.props.value === 'string';
+}
+
+export function typeText(target: ResolvedTarget, action: TypeAction, services: ActionServices): HandlerResult {
+  if (target.element.kind !== 'text_input') {
+    return failed('element_not_interactable', 'type needs a text input');
+  }
+  const verdict = checkEditable(target.fiber, target.ancestors);
+  if (!verdict.allowed) {
+    return failed('element_not_interactable', verdict.reason);
+  }
+  const next = action.clear_first ? action.value : currentTextOf(target) + action.value;
+  const instance = target.host === null ? null : hostInstanceOf(target.host);
+  try {
+    instance?.focus?.();
+    if (!isControlled(target)) {
+      if (Platform.OS === 'android') {
+        const tag = findNodeHandle(instance as Parameters<typeof findNodeHandle>[0]);
+        const eventCount = target.host === null ? undefined : propsOf(target.host).mostRecentEventCount;
+        if (tag === null || typeof eventCount !== 'number' || !Number.isInteger(eventCount) || eventCount < 0) {
+          return failed('element_not_interactable', 'the native text input is unavailable');
+        }
+        UIManager.dispatchViewManagerCommand(tag, 'setTextAndSelection', [eventCount, next, next.length, next.length]);
+      } else {
+        instance?.setNativeProps?.({ text: next });
+      }
+    }
+    const { onChange, onChangeText } = target.props;
+    runBatched(() => {
+      if (isFunction(onChange)) {
+        onChange(buildTextChangeEvent(next));
+      }
+      if (isFunction(onChangeText)) {
+        onChangeText(next);
+      }
+    });
+  } catch (error) {
+    return failedFromException(error);
+  }
+  services.inputMemory.last = target.element;
+  return succeeded();
+}
+
+export function submitInput(target: ResolvedTarget): HandlerResult {
+  if (target.element.kind !== 'text_input') {
+    return failed('element_not_interactable', 'Enter needs a text input');
+  }
+  const onSubmitEditing = target.props.onSubmitEditing;
+  if (!isFunction(onSubmitEditing)) {
+    return failed('element_not_interactable', 'the input has no onSubmitEditing handler');
+  }
+  try {
+    runBatched(() => onSubmitEditing(buildSubmitEvent(currentTextOf(target))));
+    return succeeded();
+  } catch (error) {
+    return failedFromException(error);
+  }
+}

package/src/actions/types.ts

@@ -0,0 +1,52 @@
+import type { UnknownRecord } from '../fiber/narrow.ts';
+
+export type ScrollDirectionName = 'up' | 'down' | 'left' | 'right';
+
+export type AgentAction =
+  | { type: 'click' }
+  | { type: 'type'; value: string; clear_first: boolean }
+  | { type: 'check'; checked: boolean | null }
+  | { type: 'press_key'; key: string }
+  | { type: 'scroll'; direction: ScrollDirectionName; amount: number | null }
+  | { type: 'scroll_to' }
+  | { type: 'navigate'; route: string; params: UnknownRecord | null }
+  | { type: 'highlight' };
+
+export type ActionErrorCode =
+  | 'element_not_found'
+  | 'element_not_interactable'
+  | 'unsupported_action'
+  | 'execution_error'
+  | 'user_cancelled'
+  | 'timeout';
+
+export type RiskLevel = 'safe' | 'reversible' | 'irreversible' | 'destructive';
+
+export type FailedResult = { ok: false; error: ActionErrorCode; message: string };
+
+export type HandlerResult = { ok: true; message?: string } | FailedResult;
+
+export interface ActionOutcome {
+  success: boolean;
+  no_op: boolean;
+  error?: ActionErrorCode;
+  message?: string;
+}
+
+export interface PageContentRequest {
+  viewportOnly: boolean;
+  maxChars: number;
+}
+
+export interface AgentCommandData {
+  command_id: string;
+  action: AgentAction;
+  agent_id: string | null;
+  risk_level: RiskLevel;
+  confirmation_required: boolean;
+  teaching_explanation: string | null;
+  include_page_content: boolean;
+  page_content_options: PageContentRequest;
+  dom_settle_ms: number;
+}
+

package/src/agent/batch-commands.ts

@@ -0,0 +1,33 @@
+import { parseAgentCommand, parsePageContentRequest } from '../actions/parse.ts';
+import type { AgentCommandData, PageContentRequest } from '../actions/types.ts';
+import { isRecord, nonEmptyString } from '../fiber/narrow.ts';
+
+export type BatchEntry =
+  | { kind: 'action'; command: AgentCommandData }
+  | { kind: 'dom_state'; commandId: string }
+  | { kind: 'text_dom'; commandId: string; options: PageContentRequest }
+  | { kind: 'invalid'; commandId: string; reason: string };
+
+function parseEntry(raw: unknown): BatchEntry {
+  if (!isRecord(raw)) {
+    return { kind: 'invalid', commandId: '', reason: 'malformed batch entry' };
+  }
+  const commandId = nonEmptyString(raw.command_id) ?? '';
+  switch (raw.type) {
+    case 'request_dom_state':
+      return { kind: 'dom_state', commandId };
+    case 'request_text_dom':
+      return { kind: 'text_dom', commandId, options: parsePageContentRequest(raw.options) };
+    case 'agent_command': {
+      const command = parseAgentCommand(raw);
+      return command === null ? { kind: 'invalid', commandId, reason: 'unsupported or malformed action' } : { kind: 'action', command };
+    }
+    default:
+      return { kind: 'invalid', commandId, reason: `unknown batch entry "${String(raw.type)}"` };
+  }
+}
+
+export function parseBatchEntries(data: unknown): BatchEntry[] {
+  const commands = isRecord(data) && Array.isArray(data.commands) ? data.commands : [];
+  return commands.map(parseEntry);
+}

package/src/agent/compose.ts

@@ -0,0 +1,67 @@
+import { ActionExecutor } from '../actions/executor.ts';
+import { CommitWatch } from '../actions/commit-watch.ts';
+import { NavigationDriver, type NavigationRefLike } from '../actions/navigation-driver.ts';
+import type { CursorPort } from '../actions/landing.ts';
+import type { ActionServices, ReadingPort } from '../actions/services.ts';
+import { TargetResolver } from '../actions/target.ts';
+import type { Fiber } from '../fiber/types.ts';
+import type { Size } from '../host/rect.ts';
+import type { ConfirmationPort } from '../confirmation/port.ts';
+import type { AgentStage } from './stage.ts';
+import { Screenshotter } from '../screenshot/screenshotter.ts';
+import { SnapshotCapturer } from '../snapshot/capture.ts';
+import type { ScreenRef } from '../snapshot/navigation.ts';
+import { ElementContextReader } from '../snapshot/element-context.ts';
+import { ElementRegistry } from '../snapshot/registry.ts';
+import type { AgentTransport } from '../transport/transport.ts';
+import { AgentController } from './controller.ts';
+
+export interface AgentEnvironment {
+  transport: AgentTransport;
+  getAnchorFiber: () => Fiber | null;
+  getViewport: () => Size;
+  getNavigationRef: () => NavigationRefLike | null;
+  getCaptureTarget: () => unknown;
+  reading: ReadingPort;
+  cursor: CursorPort;
+  confirmation: ConfirmationPort;
+  stage: AgentStage;
+  onCommit?: () => void;
+  onSettled?: () => void;
+}
+
+export function createAgentController(environment: AgentEnvironment): AgentController {
+  const registry = new ElementRegistry();
+  const navigation: NavigationDriver = new NavigationDriver({
+    readFocusedScreens: (): ScreenRef[] => capturer.readFocusedScreens(),
+    getNavigationRef: environment.getNavigationRef,
+  });
+  const capturer: SnapshotCapturer = new SnapshotCapturer({
+    getAnchorFiber: environment.getAnchorFiber,
+    registry,
+    getViewport: environment.getViewport,
+    getExtraRoutes: (): string[] => navigation.listRefRoutePaths(),
+  });
+  const commitWatch = new CommitWatch(environment.getAnchorFiber, environment.onCommit);
+  const services: ActionServices = {
+    resolver: new TargetResolver(registry, environment.getAnchorFiber),
+    navigation,
+    reading: environment.reading,
+    cursor: environment.cursor,
+    inputMemory: { last: null },
+  };
+  return new AgentController({
+    transport: environment.transport,
+    commitWatch,
+    getViewport: environment.getViewport,
+    onSettled: environment.onSettled,
+    context: {
+      capturer,
+      executor: new ActionExecutor(capturer, services, commitWatch),
+      screenshotter: new Screenshotter(environment.getCaptureTarget),
+      elementContext: new ElementContextReader(services.resolver, environment.getViewport),
+      confirmation: environment.confirmation,
+      stage: environment.stage,
+    },
+  });
+}

package/src/agent/controller.ts

@@ -0,0 +1,106 @@
+import type { CommitWatch } from '../actions/commit-watch.ts';
+import { readAppInfo } from '../backend/app-info.ts';
+import { buildMessageMetadata, type MessageMetadata } from '../backend/message-metadata.ts';
+import type { Size } from '../host/rect.ts';
+import { reportSdkError } from '../telemetry/sdk-reporter.ts';
+import type { AgentTransport } from '../transport/transport.ts';
+import { runFrame } from './frame-runner.ts';
+import { type OutboundFrame, parseInboundFrame, type RoutedFrame } from './frames.ts';
+import { handleAgentCommand } from './handlers/agent-command.ts';
+import { handleBatch } from './handlers/batch.ts';
+import type { HandlerContext } from './handlers/context.ts';
+import { handleDomState } from './handlers/dom-state.ts';
+import { handleElementContext } from './handlers/element-context.ts';
+import { handleScreenshot } from './handlers/screenshot.ts';
+import { handleTextDom, readTextDom } from './handlers/text-dom.ts';
+
+export interface ControllerDependencies {
+  transport: AgentTransport;
+  commitWatch: CommitWatch;
+  getViewport: () => Size;
+  context: Omit<HandlerContext, 'send'>;
+  onSettled?: () => void;
+}
+
+
+export class AgentController {
+  private queue: Promise<void> = Promise.resolve();
+
+  private readonly context: HandlerContext;
+
+  constructor(private readonly dependencies: ControllerDependencies) {
+    this.context = { ...dependencies.context, send: (frame) => this.send(frame) };
+  }
+
+  start(): void {
+    this.dependencies.transport.onMessage((raw) => this.receive(raw));
+    this.dependencies.transport.start();
+  }
+
+  stop(): void {
+    this.dependencies.transport.stop();
+    this.dependencies.commitWatch.release();
+  }
+
+  async readMessageMetadata(options: { includeTextDom: boolean; tabId: string }): Promise<MessageMetadata> {
+    const snapshot = await this.context.capturer.capture('peek');
+    const textDom = options.includeTextDom ? await readTextDom(this.context, { viewportOnly: false, maxChars: 0 }) : null;
+    return buildMessageMetadata({
+      screen: snapshot.screen,
+      tabId: options.tabId,
+      viewport: this.dependencies.getViewport(),
+      appInfo: readAppInfo(),
+      textDom,
+    });
+  }
+
+  private receive(raw: string): void {
+    const frame = parseInboundFrame(raw);
+    if (frame === null || frame.kind === 'unknown') {
+      return;
+    }
+    if (frame.kind === 'ping') {
+      this.send({ type: 'pong' });
+      return;
+    }
+    this.send({ type: 'command_ack', command_id: frame.commandId });
+    this.queue = this.queue
+      .then(() => runFrame(frame, { stage: this.context.stage, handle: (next) => this.handle(next), onSettled: this.dependencies.onSettled }))
+      .catch((error: unknown) => reportSdkError('AgentController.receive', error));
+  }
+
+  private async handle(frame: RoutedFrame): Promise<void> {
+    try {
+      await this.route(frame);
+    } catch (error) {
+      reportSdkError('AgentController.handle', error);
+      this.send({
+        type: 'sdk_error',
+        command_id: frame.commandId,
+        error: error instanceof Error ? error.message : String(error),
+        code: 'execution_error',
+      });
+    }
+  }
+
+  private route(frame: RoutedFrame): Promise<void> {
+    switch (frame.kind) {
+      case 'agent_command':
+        return handleAgentCommand(this.context, frame.commandId, frame.data);
+      case 'agent_command_batch':
+        return handleBatch(this.context, frame.commandId, frame.data);
+      case 'request_dom_state':
+        return handleDomState(this.context, frame.commandId);
+      case 'request_text_dom':
+        return handleTextDom(this.context, frame.commandId, frame.options);
+      case 'request_screenshot':
+        return handleScreenshot(this.context, frame.commandId, frame.options);
+      case 'request_element_context':
+        return handleElementContext(this.context, frame.commandId, frame.agentIds);
+    }
+  }
+
+  private send(frame: OutboundFrame): void {
+    this.dependencies.transport.send(frame);
+  }
+}

package/src/agent/frame-runner.ts

@@ -0,0 +1,27 @@
+import { parseAgentCommand } from '../actions/parse.ts';
+import type { RoutedFrame } from './frames.ts';
+import type { Admission, AgentStage } from './stage.ts';
+
+export function admissionFor(frame: RoutedFrame): Admission | null {
+  if (frame.kind === 'agent_command') {
+    return { kind: 'command', keepText: parseAgentCommand(frame.data)?.teaching_explanation ?? null };
+  }
+  return frame.kind === 'agent_command_batch' ? { kind: 'batch', keepText: null } : null;
+}
+
+export interface FrameRunnerOptions {
+  stage: AgentStage;
+  handle: (frame: RoutedFrame) => Promise<void>;
+  onSettled?: () => void;
+}
+
+export async function runFrame(frame: RoutedFrame, options: FrameRunnerOptions): Promise<void> {
+  options.stage.received();
+  const admission = admissionFor(frame);
+  if (admission !== null && !(await options.stage.admit(admission))) {
+    return;
+  }
+  await options.handle(frame);
+  options.stage.settled();
+  options.onSettled?.();
+}