Type System Reference

interface ShellExecutor {
  exec(command: string, options?: ShellExecOptions): Promise<string>;
}

interface ShellExecOptions {
  timeoutMs?: number;    // Default: 30,000ms (TIMEOUTS.SHELL_COMMAND_MS)
  signal?: AbortSignal;  // For cancellation
}

class HelperClient {
  constructor(hostPort: number, defaultTimeoutMs?: number);

  status(timeoutMs?: number): Promise<HelperStatus | null>;
  waitForReady(timeoutMs?: number, expectedProtocolVersion?: number): Promise<HelperStatus>;
  getTree(opts?: { compact?: boolean; packageName?: string }): Promise<HelperJson>;
  detectFramework(packageName?: string): Promise<HelperFrameworkInfo>;
  waitForIdle(opts?: { timeoutMs?: number; packageName?: string }): Promise<HelperIdleResult>;
  screenshot(): Promise<string>; // base64 PNG
  tap(x: number, y: number): Promise<void>;
  swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
  longPress(x: number, y: number, durationMs: number): Promise<void>;
  key(keycode: number): Promise<void>;
  typeText(text: string): Promise<void>;
  shutdown(): Promise<void>;
}

interface HelperStatus {
  ok: boolean;
  name: string;
  version: string;
  protocolVersion: number;
  sdkInt: number;
  device: string;
  manufacturer: string;
}

interface HelperFrameworkInfo {
  ok: boolean;
  packageName: string;
  primary: 'flutter' | 'react_native' | 'compose' | 'native';
  frameworks: string[];   // e.g. ['react_native', 'react_native_hermes']
  signals: string[];      // detection evidence: 'class:...', 'lib:...'
}

interface HelperIdleResult {
  ok: boolean;
  idle: boolean;
  reason: string;         // 'events_quiet' | 'timeout'
  events: string[];       // accessibility event names recorded
}

interface FrameworkSyncInit {
  framework: 'flutter' | 'react_native' | 'compose' | 'native';
  packageName: string;
  adb: AdbClient;
}

class FrameworkSync {
  constructor(init: FrameworkSyncInit);

  /** The framework kind passed at construction. */
  get kind(): FrameworkKind;

  /** True iff any sync channel attached successfully. */
  get hasBackend(): boolean;
  /** True iff the Hermes CDP channel connected (RN debug + Metro running). */
  get hasHermes(): boolean;
  /** True iff the Dart VM Service channel connected (Flutter debug/profile). */
  get hasDartVm(): boolean;
  /** True iff the user's app declared the agentest-idling-bridge provider. */
  get hasIdlingBridge(): boolean;

  /**
   * In-band diagnostic trace surfaced through tool responses — one
   * human-readable line per channel event. Appended by each backend
   * during `attach()` + `waitForSync()` + `snapshotFiberLabels()`.
   * Tools slice out new lines after each call to return to the LLM.
   */
  get diagnostics(): string[];

  /** Open all applicable channels. Non-fatal per-channel; safe to call once. */
  attach(): Promise<void>;

  /** Tail probe after helper /wait-idle. Returns false only on channel timeout. */
  waitForSync(timeoutMs?: number): Promise<boolean>;

  /** Force Flutter semantics to build. Dart VM channel only. */
  refreshSemantics(): Promise<boolean>;

  /**
   * Extract React component names from the running Hermes JS runtime and
   * correlate them with `tree`'s accessibility nodes by bounds containment.
   * Returns a map of `nodeId → label` suitable for passing to
   * `serializeTreeCompact` as `externalLabels`. Cached by screen
   * fingerprint so multi-step flows don't re-extract on every snapshot.
   *
   * Silent no-op when framework !== 'react_native', Hermes is unattached,
   * or `AGENTEST_DISABLE_FIBER_INFERENCE=1`. Returns an empty map on
   * failure — callers fall through to Phase 3.5 hoisting.
   */
  snapshotFiberLabels(tree: UnifiedUINode): Promise<Map<string, string>>;

  /** Release all WebSockets. Safe to call multiple times. */
  close(): void;
}

interface HelperHandle {
  client: HelperClient;
  status: HelperStatus;
  shutdown(uninstall?: boolean): Promise<void>;
}

function ensureHelper(
  shell: ShellExecutor,
  deviceId?: string,
  options?: { startupTimeoutMs?: number },
): Promise<HelperHandle | null>;

interface Bounds {
  left: number;    // Pixels, screen-absolute
  top: number;
  right: number;
  bottom: number;
}

interface Point {
  x: number;  // Pixels, screen-absolute
  y: number;
}

interface UnifiedUINode {
  // Identity
  id: string;              // Generated path-based ID (e.g., "0.1.3")
  resourceId: string;      // Android resource-id (e.g., "com.example:id/email")
  className: string;       // Raw Android class name
  role: UnifiedRole;       // Abstract mapped role
  text: string;            // Visible text content
  description: string;     // Content description (accessibility label)
  packageName: string;     // App package name
  
  // Geometry
  bounds: Bounds;          // Screen-absolute pixel bounds
  center: Point;           // Center point (computed from bounds)
  index: number;           // Sibling index (0-based)
  
  // State flags (from Android AccessibilityNodeInfo)
  enabled: boolean;
  focused: boolean;
  selected: boolean;
  checked: boolean;
  checkable: boolean;
  clickable: boolean;
  scrollable: boolean;
  longClickable: boolean;
  password: boolean;

  // Phase 3.8 Compose extras — empty string when absent
  hintText: string;         // AccessibilityNodeInfo.hintText (API 26+)
  stateDescription: string; // AccessibilityNodeInfo.stateDescription (API 28+)
  paneTitle: string;        // AccessibilityNodeInfo.paneTitle (API 28+)
  tooltipText: string;      // AccessibilityNodeInfo.tooltipText (API 28+)
  
  // Derived
  actions: UnifiedAction[];    // Available interactions
  children: UnifiedUINode[];   // Child nodes
}

const UNIFIED_ROLES = {
  BUTTON: 'button',
  TEXT_FIELD: 'text_field',
  TEXT_VIEW: 'text_view',
  CHECK_BOX: 'check_box',
  SWITCH: 'switch',
  RADIO_BUTTON: 'radio_button',
  SLIDER: 'slider',
  SCROLL_VIEW: 'scroll_view',
  IMAGE: 'image',
  IMAGE_BUTTON: 'image_button',
  CONTAINER: 'container',
  LIST: 'list',
  LIST_ITEM: 'list_item',
  TAB: 'tab',
  TOOLBAR: 'toolbar',
  PROGRESS_BAR: 'progress_bar',
  SPINNER: 'spinner',
  WEB_VIEW: 'web_view',
  UNKNOWN: 'unknown',
} as const;

type UnifiedRole = (typeof UNIFIED_ROLES)[keyof typeof UNIFIED_ROLES];

const UNIFIED_ACTIONS = {
  TAP: 'tap',
  LONG_PRESS: 'long_press',
  TYPE: 'type',
  SCROLL: 'scroll',
  CHECK: 'check',
  ADJUST: 'adjust',
} as const;

const ElementSelectorSchema = z.object({
  /**
   * Short ref token from the last tree snapshot (e.g. "@b1", "@f2").
   * When set, ref takes priority over all other fields — they are ignored.
   * If the ref is stale, throws ElementNotFoundError with an actionable
   * message telling the LLM to call agentest_get_ui_tree for fresh refs.
   * No automatic fallback to other selector fields.
   */
  ref: z.string().optional(),
  id: z.string().optional(),
  text: z.string().optional(),
  textContains: z.string().optional(),
  className: z.string().optional(),
  description: z.string().optional(),
  index: z.number().int().nonnegative().optional(),
});

type ElementSelector = z.infer<typeof ElementSelectorSchema>;

interface StepResult {
  stepIndex: number;       // 0-based position in the steps array
  action: ActionStep;      // The step that was executed
  success: boolean;        // Whether the step passed
  durationMs: number;      // Wall-clock time for this step
  error?: string;          // Human-readable error (only on failure)
  loadingDetected?: string; // Description of loading indicators waited out (if any)
}

interface FlowTrace {
  success: boolean;            // true if ALL steps passed
  stepsCompleted: number;      // Number of steps executed (may be < totalSteps on failure)
  totalSteps: number;          // Total steps in the flow
  results: StepResult[];       // Per-step results
  /** 6-char screen fingerprint (always present). */
  screenFingerprint: string;
  /**
   * True when the screen meaningfully changed during the flow. False when
   * the UI is exactly where you started — typing into a field does NOT
   * flip this flag (in-place mutation, not a screen change).
   */
  screenChanged: boolean;
  /**
   * Compact text snapshot at the end (or at point of failure). **Omitted
   * entirely** when screenChanged is false AND success is true — when
   * nothing changed and everything passed, there's nothing new to report
   * and the tree would just burn tokens.
   */
  finalUiTree?: string;
  error?: string;              // Top-level error message (only on failure)
  systemDialogs?: SystemDialog[]; // Permission prompts, crash dialogs detected during flow
  appCrashDetected?: boolean;  // True if the app process died (root package changed to system)
}

class RefRegistry {
  /**
   * Walk a fresh tree, assign refs, compute fingerprint, and cache the
   * compact text result. Call this every time the tree changes.
   */
  rebuild(tree: UnifiedUINode, opts?: CompactSerializeOptions): CompactSerializeResult;

  /**
   * O(1) lookup. Throws ElementNotFoundError with stale-ref message if the
   * ref doesn't exist — tells the LLM to call agentest_get_ui_tree.
   * No automatic fallback to other selector fields.
   */
  resolve(ref: string): UnifiedUINode;

  get fingerprint(): string;  // 6-char hash from last rebuild
  get text(): string;         // compact text from last rebuild
  get size(): number;         // total refs in current map
  clear(): void;              // drop all state (called on connect)
}

interface CompactSerializeOptions {
  /** Hard cap on emitted lines. Defaults to 200. */
  maxLines?: number;
  /** Max indent depth. 0 = unlimited (default). */
  maxDepth?: number;
  /** Drop plain text lines. Defaults to false. */
  onlyInteractive?: boolean;
  /**
   * External labels keyed by node id — fiber-derived component names
   * from `FrameworkSync.snapshotFiberLabels()` (Phase 3.6). When a node
   * has an external label, the serializer prefers it over hoisted labels
   * over own labels. Makes unlabeled icon buttons in RN codegen apps
   * resolvable by the LLM without any target-app code changes.
   */
  externalLabels?: Map<string, string>;
}

interface CompactSerializeResult {
  text: string;                            // indented text representation
  fingerprint: string;                     // 6-char screen fingerprint
  refMap: Map<string, UnifiedUINode>;      // @ref → node
  refCount: number;                        // total refs assigned
  lineCount: number;                       // lines emitted
  truncated: boolean;                      // true if maxLines kicked in
}

/**
 * Idle fingerprint: stable across cursor blink + bounds jitter + live
 * timestamps. Used by idle.ts. Includes EditText text content because
 * typing IS a UI change for idle detection purposes.
 */
function computeIdleFingerprint(node: UnifiedUINode): string;

/**
 * Screen fingerprint: 6-char hash. Used by run_flow's screenChanged gate.
 * Critical: EXCLUDES EditText text content — typing should not flip the
 * fingerprint (concern #1 from the design review). The LLM verifies type
 * success via assertions or the final tree on !success.
 */
function computeScreenFingerprint(node: UnifiedUINode): string;

interface LlmTreeNode {
  id?: string;          // Only when resource-id is non-empty
  role: string;         // Always present
  text?: string;        // Only when non-empty
  desc?: string;        // Only when content description is non-empty
  cls?: string;         // Short class name for unlabeled elements (e.g. "ReactViewGroup")
  hint?: string;        // Phase 3.8 — hintText (API 26+). Compose TextField placeholder etc.
  state?: string;       // Phase 3.8 — stateDescription (API 28+). Compose Switch state etc.
  pane?: string;        // Phase 3.8 — paneTitle (API 28+). Compose Scaffold / navigation panes.
  tooltip?: string;     // Phase 3.8 — tooltipText (API 28+).
  bounds: string;       // Always present, format: "[left,top][right,bottom]"
  clickable?: true;     // Only for unlabeled tappable elements
  enabled?: false;      // Only when disabled (enabled is the default)
  checked?: true;       // Only when checked
  focused?: true;       // Only when focused
  selected?: true;      // Only when selected
  password?: true;      // Only for password fields
  scrollable?: true;    // Only for scrollable containers
  actions?: string[];   // Only when actions are available
  children?: LlmTreeNode[];  // Only when children exist
}